shield_lock
JinDaGe
← Back to MCP directory
publicPublicdnsLocal runtime

kulturpool_mcp_server

这是一个通过Model Context Protocol（MCP）访问奥地利文化遗产数据（Kulturpool API）的服务器。它采用渐进式披露架构，提供6个工具进行安全、高效的搜索和浏览，包括探索、筛选搜索、获取详情、机构查询和资源获取等功能。

article

README

🚀 奥地利文化遗产MCP服务器

本项目是一个基于模型上下文协议（MCP）的服务器，借助Kulturpool API实现奥地利文化遗产的搜索功能，为用户提供便捷、安全且高效的文化遗产信息查询服务。

🚀 快速开始

前提条件

  • Python 3.8 或更高版本
  • pip 包管理器
  • Git（用于克隆仓库）

安装步骤

  1. 克隆仓库：

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

  2. 创建并激活虚拟环境：

    Windows：

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

    Linux/WSL/macOS：

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

  3. 安装依赖：

    pip install -r requirements.txt

  4. 测试服务器：

    Windows：

    python server.py

    Linux/WSL/macOS：

    python3 server.py

Claude桌面配置

将服务器添加到Claude桌面MCP配置文件中：

配置文件位置：

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

选项1：使用WSL的Windows系统（本项目推荐）

{
  "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"
      }
    }
  }
}

选项2：原生Windows系统

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

选项3：Linux/macOS系统

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

Claude代码配置

对于WSL/Linux环境中的Claude代码：

{
  "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"
      }
    }
  }
}

📝 注意：mcp_config.json 中提供了预配置选项，可将相关部分复制到您的配置文件中。

替代方法：启动脚本

Windows：

run_server.bat

Linux/WSL/macOS：

chmod +x run_server.sh
./run_server.sh

✨ 主要特性

🔍 六工具渐进式披露架构

  1. kulturpool_explore - 初始探索，进行分面分析（响应小于2KB）
  2. kulturpool_search_filtered - 带综合过滤器的目标搜索（最多20个结果）
  3. kulturpool_get_details - 使用基于内容的搜索查找相关对象（最多3个ID）
  4. kulturpool_get_institutions - 包含位置信息的完整机构目录
  5. kulturpool_get_institution_details - 详细的机构元数据
  6. kulturpool_get_assets - 经过优化和转换的图像资源

🛡️ 内置安全机制

  • 输入清理：防止注入攻击
  • 速率限制：每个客户端每小时100个请求
  • 响应限制：响应小于10KB，提高上下文效率
  • 参数验证：基于Pydantic的全面验证
  • 安全URL处理：仅限于Kulturpool API端点

⚡ 性能优化

  • 渐进式披露：从广泛搜索开始，逐步缩小范围
  • 压缩响应：仅包含必要的元数据
  • 基于分面的导航：提供智能过滤建议
  • 连接池：高效的HTTP客户端，具备重试逻辑

📦 安装指南

前提条件

  • Python 3.8 或更高版本
  • pip 包管理器
  • Git（用于克隆仓库）

安装步骤

  1. 克隆仓库：

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

  2. 创建并激活虚拟环境：

    Windows：

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

    Linux/WSL/macOS：

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

  3. 安装依赖：

    pip install -r requirements.txt

  4. 测试服务器：

    Windows：

    python server.py

    Linux/WSL/macOS：

    python3 server.py

Claude桌面配置

将服务器添加到Claude桌面MCP配置文件中：

配置文件位置：

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

选项1：使用WSL的Windows系统（本项目推荐）

{
  "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"
      }
    }
  }
}

选项2：原生Windows系统

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

选项3：Linux/macOS系统

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

Claude代码配置

对于WSL/Linux环境中的Claude代码：

{
  "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"
      }
    }
  }
}

📝 注意：mcp_config.json 中提供了预配置选项，可将相关部分复制到您的配置文件中。

替代方法：启动脚本

Windows：

run_server.bat

Linux/WSL/macOS：

chmod +x run_server.sh
./run_server.sh

💻 使用示例

基础用法

1. 初始探索

从广泛的探索开始，了解可用数据：

# 获取带分面的概述
kulturpool_explore(query="Mozart")

返回结果：按机构、类型和时间段划分的分面计数，以及示例结果。

2. 过滤搜索

使用分面缩小搜索结果范围：

# 带过滤器的目标搜索
kulturpool_search_filtered(
    query="Vienna",
    institutions=["Albertina", "Belvedere"],
    object_types=["IMAGE"],
    date_from=1800,
    date_to=1900,
    creators=["Klimt"],
    limit=15
)

高级过滤器：

  • 日期范围：采用区间重叠语义（对象的 [dateMin,dateMax] 与 [date_from,date_to] 重叠）
  • 创作者：支持通配符的部分匹配
  • 主题：主题的精确匹配
  • 媒体：按材料/媒介过滤
  • 都柏林核心类型：受性能限制的对象分类

3. 相关对象发现

使用基于内容的搜索查找相关文化对象：

# 查找相关对象
kulturpool_get_details(object_ids=["obj123", "obj456"])

4. 机构管理

探索参与的机构：

# 获取机构目录
kulturpool_get_institutions(include_locations=True, language="de")

# 获取详细的机构信息
kulturpool_get_institution_details(institution_id=42, language="de")

5. 资源优化

访问经过优化和转换的图像：

# 获取优化后的图像资源
kulturpool_get_assets(
    asset_id="logo_123",
    width=400,
    height=300,
    format="webp",
    quality=85,
    fit="inside"
)

📚 详细文档

支持的机构选择

奥地利主要的文化机构参与了Kulturpool网络：

开发

架构

服务器采用单文件实现（server.py，约1300行），具备以下特点：

  • MCP协议：传统的标准输入输出传输
  • 异步/等待：全异步操作
  • Pydantic验证：类型安全的参数处理
  • 安全层：输入清理和速率限制
  • 错误处理：全面的异常管理

关键组件

├── SecurityValidator     # 输入清理和验证
├── RateLimiter          # 请求速率限制（每小时100个）
├── KulturpoolClient     # 具备重试逻辑的HTTP客户端
├── ResponseProcessor    # 数据处理和分面分析
└── Tool Handlers        # 六个专门的工具实现

配置

环境变量

无需设置环境变量，服务器直接连接到公共的Kulturpool API。

速率限制

  • 默认值：每个客户端每小时100个请求
  • 可配置：修改 RateLimiter(max_requests=100, time_window=3600)
  • 范围：全局应用于所有工具调用

响应限制

  • 探索：带分面的响应小于2KB
  • 搜索：最多20个结果，包含完整元数据
  • 详情：每个请求最多3个对象ID
  • 总体：响应大小限制小于10KB

API参考

数据源

此服务器提供对以下API的访问：

  • 基础API：https://api.kulturpool.at/search/
  • 机构API：https://api.kulturpool.at/institutions/
  • 资源API：https://api.kulturpool.at/assets/

对象类型

  • IMAGE：照片、绘画、素描、图形
  • TEXT：手稿、书籍、文件、信件
  • SOUND：音频记录、音乐、口述历史
  • VIDEO：电影记录、纪录片
  • 3D：三维物体、雕塑

排序选项

  • titleSort:asc/desc - 按标题字母顺序排序
  • dataProvider:asc/desc - 按机构排序
  • dateMin:asc/desc - 按最早日期排序
  • dateMax:asc/desc - 按最晚日期排序

🔧 技术细节

服务器采用单文件实现（server.py，约1300行），运用了MCP协议进行传统的标准输入输出传输。通过异步/等待机制实现全异步操作，提高了服务器的响应性能。使用Pydantic进行参数验证，确保了类型安全。同时，具备输入清理和速率限制的安全层，以及全面的异常管理机制，保障了服务器的稳定性和安全性。

📄 许可证

本项目采用MIT许可证，详情请参阅 LICENSE.txt 文件。

支持

开发致谢

本MCP服务器由 奥地利科学院数字人文中心（ÖAW - ACDH） 开发，采用了 Vibe Coding 方法，并借助 Claude Code CLI 工具，在 Claude Sonnet 4 的协助下完成。

⚠️ 测试版免责声明

此MCP服务器为测试版，属于实验性软件。

  • 该软件仅经过有限测试，应视为实验性产品。
  • 在生产环境中使用需自行承担风险。
  • 开发者对因使用本软件而导致的任何损害、数据丢失或其他后果不承担责任。
  • 对于本软件的功能、可靠性或适用性，不提供任何明示或暗示的保证。

致谢

help

Runtime guide

cloud

Hosted runtime

Hosted servers run from a provider-managed environment. You usually connect the MCP client to the hosted endpoint or follow the provider's authorization flow, without keeping a local process alive

  1. Open provider connection page
  2. Authorize or copy endpoint
  3. Connect from your MCP client
terminal

Local runtime / other methods

Local servers run on your own machine or infrastructure. You normally copy the server_config into your MCP client, install the required package, and provide env variables from env_schema when needed

  1. Copy server_config
  2. Install required package
  3. Fill env variables and restart client