Kulturerbe MCP Server

Model Context Protocol (MCP) server for searching Austrian Cultural Heritage via the Kulturpool API.

Overview

This MCP server provides secure, rate-limited access to Austria's cultural heritage through the Kulturpool API. It implements a 6-tool progressive disclosure architecture designed for efficient context window usage and comprehensive cultural object discovery.

Features

🔍 6-Tool Progressive Disclosure Architecture

kulturpool_explore - Initial exploration with facet analysis (< 2KB response)
kulturpool_search_filtered - Targeted search with comprehensive filters (≤ 20 results)
kulturpool_get_details - Find related objects using content-based search (≤ 3 IDs)
kulturpool_get_institutions - Complete institution directory with locations
kulturpool_get_institution_details - Detailed institution metadata
kulturpool_get_assets - Optimized image assets with transformations

🛡️ Built-in Security

Input Sanitization: Protection against injection attacks
Rate Limiting: 100 requests/hour per client
Response Limits: < 10KB responses for context efficiency
Parameter Validation: Comprehensive Pydantic-based validation
Safe URL Handling: Restricted to Kulturpool API endpoints

⚡ Performance Optimized

Progressive Disclosure: Start broad, then narrow down
Compressed Responses: Essential metadata only
Facet-Based Navigation: Smart filtering recommendations
Connection Pooling: Efficient HTTP client with retry logic

Installation

Prerequisites

Python 3.8 or higher
pip package manager
Git (for cloning the repository)

Setup

Clone the repository:

git clone https://github.com/yourusername/kulturerbe_mcp.git
cd kulturerbe_mcp

Create and activate virtual environment:

Windows:

python -m venv .venv
.venv\Scripts\activate

Linux/WSL/macOS:

python3 -m venv .venv
source .venv/bin/activate

Install dependencies:
```
pip install -r requirements.txt
```
Test the server:

Windows:
```
python server.py
```
Linux/WSL/macOS:
```
python3 server.py
```

Claude Desktop Configuration

Add the server to your Claude Desktop MCP configuration file:

Configuration file locations:

Windows: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

Option 1: Windows with WSL (Recommended for this project)

{
  "mcpServers": {
    "kulturerbe-mcp-server": {
      "command": "wsl",
      "args": ["-e", "/home/username/kulturerbe_mcp/run_server.sh"],
      "cwd": "\\\\wsl$\\Ubuntu\\home\\username\\kulturerbe_mcp",
      "env": {
        "VIRTUAL_ENV": "/home/username/kulturerbe_mcp/.venv",
        "PATH": "/home/username/kulturerbe_mcp/.venv/bin:$PATH"
      }
    }
  }
}

Option 2: Windows Native

{
  "mcpServers": {
    "kulturerbe-mcp-server": {
      "command": "python",
      "args": ["C:\\path\\to\\kulturerbe_mcp\\server.py"],
      "cwd": "C:\\path\\to\\kulturerbe_mcp",
      "env": {}
    }
  }
}

Option 3: Linux/macOS

{
  "mcpServers": {
    "kulturerbe-mcp-server": {
      "command": "python3",
      "args": ["/path/to/kulturerbe_mcp/server.py"],
      "cwd": "/path/to/kulturerbe_mcp",
      "env": {}
    }
  }
}

Claude Code Configuration

For Claude Code in WSL/Linux environment:

{
  "mcpServers": {
    "kulturerbe-mcp-server": {
      "command": "/home/username/kulturerbe_mcp/run_server.sh",
      "args": [],
      "cwd": "/home/username/kulturerbe_mcp",
      "env": {
        "VIRTUAL_ENV": "/home/username/kulturerbe_mcp/.venv",
        "PATH": "/home/username/kulturerbe_mcp/.venv/bin:$PATH"
      }
    }
  }
}

📝 Note: Pre-configured options are available in mcp_config.json - copy the relevant section to your configuration file.

Alternative: Launcher Scripts

Windows:

run_server.bat

Linux/WSL/macOS:

chmod +x run_server.sh
./run_server.sh

Usage Guide

1. Initial Exploration

Start with broad exploration to understand available data:

# Get overview with facets
kulturpool_explore(query="Mozart")

Returns: Facet counts by institution, type, and time period with sample results.

2. Filtered Search

Use facets to narrow down results:

# Targeted search with filters
kulturpool_search_filtered(
    query="Vienna",
    institutions=["Albertina", "Belvedere"],
    object_types=["IMAGE"],
    date_from=1800,
    date_to=1900,
    creators=["Klimt"],
    limit=15
)

Advanced Filters:

Date Range: Interval overlap semantics (object's [dateMin,dateMax] overlaps [date_from,date_to])
Creators: Partial matching with wildcards
Subjects: Exact matching for topics
Media: Filter by material/medium
Dublin Core Types: Performance-limited object categorization

3. Related Object Discovery

Find related cultural objects using content-based search:

# Find related objects
kulturpool_get_details(object_ids=["obj123", "obj456"])

4. Institution Management

Explore participating institutions:

# Get institution directory
kulturpool_get_institutions(include_locations=True, language="de")

# Get detailed institution info
kulturpool_get_institution_details(institution_id=42, language="de")

5. Asset Optimization

Access optimized images with transformations:

# Get optimized image assets
kulturpool_get_assets(
    asset_id="logo_123",
    width=400,
    height=300,
    format="webp",
    quality=85,
    fit="inside"
)

Selection of supported institutions

Major Austrian cultural institutions participate in the Kulturpool network:

Albertina - Graphics and modern art
Belvedere - Austrian art and baroque collections
Österreichische Nationalbibliothek - National library and archives
Wiener Stadt- und Landesarchiv - Vienna city archives
MAK - Applied arts and contemporary art
Weltmuseum Wien - Ethnographic collections
Technisches Museum Wien - Technology and industry
Naturhistorisches Museum Wien - Natural history

Development

Architecture

The server is built as a single-file implementation (server.py, ~1300 lines) with:

MCP Protocol: Traditional stdio transport
Async/Await: Full asynchronous operation
Pydantic Validation: Type-safe parameter handling
Security Layer: Input sanitization and rate limiting
Error Handling: Comprehensive exception management

Key Components

├── SecurityValidator     # Input sanitization and validation
├── RateLimiter          # Request rate limiting (100/hour)
├── KulturpoolClient     # HTTP client with retry logic
├── ResponseProcessor    # Data processing and facet analysis
└── Tool Handlers        # Six specialized tool implementations

Configuration

Environment Variables

No environment variables required - the server connects directly to the public Kulturpool API.

Rate Limiting

Default: 100 requests per hour per client
Configurable: Modify RateLimiter(max_requests=100, time_window=3600)
Scope: Global across all tool calls

Response Limits

Explore: < 2KB responses with facets
Search: ≤ 20 results with full metadata
Details: ≤ 3 object IDs per request
Overall: < 10KB response size limit

API Reference

Data Sources

This server provides access to:

Base API: https://api.kulturpool.at/search/
Institution API: https://api.kulturpool.at/institutions/
Asset API: https://api.kulturpool.at/assets/

Object Types

IMAGE: Photographs, paintings, drawings, graphics
TEXT: Manuscripts, books, documents, letters
SOUND: Audio recordings, music, oral history
VIDEO: Film recordings, documentaries
3D: Three-dimensional objects, sculptures

Sort Options

titleSort:asc/desc - Alphabetical by title
dataProvider:asc/desc - By institution
dateMin:asc/desc - By earliest date
dateMax:asc/desc - By latest date

Contributing

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE.txt file for details.

Support

Issues: GitHub Issues
Discussions: GitHub Discussions
API Documentation: Kulturpool API

Development Credits

This MCP server was developed at the ÖAW-ACDH using Vibe Coding methodologies with assistance from Claude Sonnet 4 via the Claude Code CLI.

⚠️ Beta Disclaimer

This MCP server is a beta version and experimental software.

This software has undergone limited testing and should be considered experimental
Use at your own risk in production environments
The developers assume no liability for any damages, data loss, or other consequences arising from the use of this software
No warranty is provided, either express or implied, regarding the functionality, reliability, or suitability of this software for any particular purpose

Acknowledgments

Kulturpool - Austrian Cultural Heritage Platform
Model Context Protocol - Protocol specification
Anthropic - Claude Desktop integration
Austrian Academy of Sciences - Research institution support

Kulturpool Austria