Vamdc MCP

VAMDC MCP服务器

A. 模型上下文协议 用于访问VAMDC（虚拟原子和分子数据中心）光谱数据库的(MCP)服务器。

概述

通过模型上下文协议（Model Context Protocol）提供访问VAMDC光谱数据库的MCP服务器。基于（此处“Built on”后应接具体的技术或平台名称，但原文未给出，故翻译为泛指的“基于”） pyVAMDC 用于查询全球分布式数据库中的原子和分子数据。

特点/功能

• 5个MCP工具 用于查询光谱数据：

- get_server_info - 服务器功能和元数据 - get_nodes - 列出所有可用的VAMDC数据库节点（33个数据库） - get_species - 获取化学物质数据（4,952+种物质） - get_species_by_node - 根据特定数据库节点过滤物种 - get_lines - 查询波长范围内的光谱线

• 双传输支持：

- HTTP（超文本传输协议） (Streamable HTTP) - 用于网页/远程访问 - stdio（在中文中通常直接保留原样，不翻译，因为它是一个专有名词，代表标准输入输出库） - 对于桌面MCP客户端（Claude桌面版、集成开发环境）

• 清洁架构模块级工具注册，使用线程池进行异步执行

要求

• Python 3.13及以上版本
• 紫外线 包管理器

安装

克隆仓库：

git clone https://github.com/VAMDC/vamdc-mcp.git
cd vamdc-mcp

无需额外安装 uv 将自动处理依赖关系。

使用

启动服务器

HTTP传输（默认）

启动支持HTTP传输的服务器以实现网页/远程访问：

uv run server.py --transport http --port 8888

服务器将在 http://localhost:8888/mcp

更改端口 （可选）：

uv run server.py --transport http --port 9000

stdio 传输

为桌面MCP客户端启动带有stdio传输的服务器：

uv run server.py --transport stdio

这种模式被桌面应用程序（如Claude Desktop、VSCode扩展等）所使用。

命令行选项

uv run server.py --help

选项:

• --transport {http,stdio} - 传输协议（默认： http)
• --port PORT - 用于HTTP传输的端口（默认： 8888）

示例

HTTP传输示例

使用 curl 与HTTP服务器进行交互：

# 1. Initialize the session
curl -X POST "http://localhost:8888/mcp" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc":"2.0",
    "id":1,
    "method":"initialize",
    "params":{
      "protocolVersion":"2025-03-26",
      "capabilities":{},
      "clientInfo":{"name":"test-client","version":"1.0.0"}
    }
  }'

# 2. List available tools
curl -X POST "http://localhost:8888/mcp" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

# 3. Get database nodes
curl -X POST "http://localhost:8888/mcp" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc":"2.0",
    "id":3,
    "method":"tools/call",
    "params":{"name":"get_nodes","arguments":{}}
  }'

# 4. Get species from specific node (AMDIS Ionization)
curl -X POST "http://localhost:8888/mcp" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc":"2.0",
    "id":4,
    "method":"tools/call",
    "params":{
      "name":"get_species_by_node",
      "arguments":{"node_url":"http://dbshino.nifs.ac.jp:4000/vamdc/tap/"}
    }
  }'

# 5. Query spectral lines (1000-1500 Angstrom, Magnesium from VALD)
curl -X POST "http://localhost:8888/mcp" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc":"2.0",
    "id":5,
    "method":"tools/call",
    "params":{
      "name":"get_lines",
      "arguments":{
        "lambda_min":1000.0,
        "lambda_max":1500.0,
        "listNodes":["http://vald.astro.uu.se/atoms-12.07/tap/"],
        "listSpecies":["FYYHWMGAXLPEAU-UHFFFAOYSA-N"]
      }
    }
  }'

stdio 传输示例

使用回显/管道进行标准输入输出通信：

# Send initialize request
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | uv run server.py --transport stdio

# Interactive session with multiple requests
cat <<'EOF' | uv run server.py --transport stdio
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}
{"jsonrpc":"2.0","method":"notifications/initialized"}
{"jsonrpc":"2.0","id":2,"method":"tools/list"}
{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"get_server_info","arguments":{}}}
EOF

Claude 桌面配置

要在Claude Desktop中使用，请在您的Claude Desktop配置文件中添加：

macOS（苹果电脑操作系统）： ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

选项1：使用启动脚本（推荐）

{
  "mcpServers": {
    "vamdc": {
      "command": "bash",
      "args": ["/path/to/vamdc-mcp/start_server.sh"]
    }
  }
}

选项2：直接执行uv命令

{
  "mcpServers": {
    "vamdc": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/vamdc-mcp",
        "server.py",
        "--transport",
        "stdio"
      ]
    }
  }
}

替换 /path/to/vamdc-mcp 使用您克隆的仓库的实际路径。

注该 start_server.sh 为方便起见，已包含脚本，该脚本可自动处理目录导航。

OpenAI Codex

将本地MCP添加到Codex，只需执行以下命令，该命令需在本仓库的根目录下运行：

codex mcp add vamdc -- uv run server.py --transport stdio

之后，这些工具即可在Codex会话中使用。

可用工具

1. 获取服务器信息

获取服务器元数据和功能。

参数无

退货服务器名称、版本、可用工具列表

2. 获取节点（或：获取节点列表）

列出所有VAMDC数据库节点。

参数无

退货33个带有元数据（名称、TAP端点、主题、联系信息）的数据库节点

3. 获取物种（get_species）

获取所有化学物质的数据。

参数：

• state (字符串): 状态过滤器（当前未实现，接受任何值）

回报4,952+种物种，包含InChI（国际化学标识）、InChIKey（InChI密钥）、化学式、电荷、质量

4. 通过节点获取物种信息

按特定数据库节点筛选物种。

参数：

• node_url (字符串)：数据库节点的TAP终端节点URL

- 示例： "http://vald.astro.uu.se/atoms-12.07/tap/"

退货从指定节点过滤后的物种列表

5. 获取行（或：获取线条）

查询波长范围内的光谱线。

参数：

• lambda_min (float): 波长的下限，以埃为单位（必填）
• lambda_max (float): 上波长界限（以埃为单位）（必填）
• listNodes （字符串数组，可选）：按 TAP 端点 URL 过滤
• listSpecies （字符串数组，可选）：按InChI键过滤

回报光谱线数据，包括频率、爱因斯坦系数、能级、量子数

注这个工具用于查询远程的VAMDC（虚拟天文数据中心）数据库，根据波长范围和过滤器的不同，查询可能会较慢或出现超时。

建筑学

• FastMCP 框架基于官方MCP Python实现构建
• 异步执行线程池执行阻塞式数据库操作
• 无状态HTTP请求之间不维护会话状态
• 模块级工具简洁、平整的结构，便于维护

依赖项

由（系统/程序等）自动管理 uv：

• mcp - 模型上下文协议实现
• uvicorn - 用于HTTP传输的ASGI服务器
• pyVAMDC - 用于VAMDC数据库的Python接口（)

- 处理对远程VAMDC TAP端点的查询 - 从多个数据库中处理光谱数据 - 提供过滤和数据处理工具

测试

见 mcp_server_test_log.md 用于全面测试文档。

协议版本

实现了MCP协议版本 2025年03月26日

许可证

请参阅仓库以获取许可信息。

贡献

欢迎贡献！请在GitHub上提交问题或拉取请求。

链接

• VAMDC门户
• 模型上下文协议

-