Kulturpool MCP Server

🚀 Kulturerbe MCP Server

This Model Context Protocol (MCP) server enables users to search Austrian Cultural Heritage through the Kulturpool API. It offers secure and rate - limited access to a wealth of cultural resources, facilitating efficient discovery of cultural objects.

🚀 Quick Start

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 for efficient context window usage and comprehensive cultural object discovery.

✨ Features

🔍 6 - Tool Progressive Disclosure Architecture

1. kulturpool_explore: Conduct an initial exploration with facet analysis (response size < 2KB).
2. kulturpool_search_filtered: Perform a targeted search with comprehensive filters (≤ 20 results).
3. kulturpool_get_details: Find related objects using content - based search (≤ 3 IDs).
4. kulturpool_get_institutions: Access the complete institution directory with locations.
5. kulturpool_get_institution_details: Obtain detailed institution metadata.
6. kulturpool_get_assets: Get optimized image assets with transformations.

🛡️ Built - in Security

• Input Sanitization: Protect against injection attacks.
• Rate Limiting: Limit to 100 requests per hour per client.
• Response Limits: Keep responses < 10KB for context efficiency.
• Parameter Validation: Implement comprehensive Pydantic - based validation.
• Safe URL Handling: Restrict to Kulturpool API endpoints.

⚡ Performance Optimized

• Progressive Disclosure: Start with a broad search and then narrow down.
• Compressed Responses: Only include essential metadata.
• Facet - Based Navigation: Provide smart filtering recommendations.
• Connection Pooling: Use an efficient HTTP client with retry logic.

📦 Installation

Prerequisites

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

Setup

1. Clone the repository:

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

2. Create and activate virtual environment: Windows:

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

   Linux/WSL/macOS:

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

3. Install dependencies:

   pip install -r requirements.txt
   

4. 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 Examples

Basic Usage

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.

Advanced Usage

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](https://www.nhm - wien.ac.at/) - Natural history

🔧 Technical Details

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

📚 Documentation

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

1. Fork the repository.
2. Create a feature branch (git checkout -b feature/amazing - feature).
3. Commit your changes (git commit -m 'Add amazing feature').
4. Push to the branch (git push origin feature/amazing - feature).
5. 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.

⚠️ Important Note

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