wikidata-mcp-server

---

概述

Wikidata 的知识图谱。搜索和获取实体，通过 SPARQL 遍历图谱，并将 DOI、PMID、ORCID、OpenAlex 和 IMDb 等外部标识符解析为对应的 Wikidata 条目。无需 API 密钥。

工具

工具	描述
wikidata_search_entities	按文本查询搜索条目或属性，返回 QID/PID 及其标签、描述和匹配元数据
wikidata_get_entity	按 QID 或 PID 获取完整实体，可选按字段和语言筛选
wikidata_get_labels	批量将最多 50 个 QID 或 PID 转换为易读的标签和描述
wikidata_get_statements	获取实体的属性声明，包含限定符详情和 QID 标签解析
wikidata_get_sitelinks	获取 Wikidata 条目对应的 Wikipedia 和 Wikimedia 项目文章 URL
wikidata_sparql_query	对 Wikidata Query Service 执行 SPARQL SELECT 查询
wikidata_resolve_external_id	通过外部标识符（DOI、PubMed ID、ORCID、OpenAlex ID 等）查找 Wikidata 实体

资源

资源	描述
wikidata://entity/{id}	Wikidata 实体的精简 Markdown 摘要——包含标签、英文描述、instance-of、Wikipedia 链接、图片和声明数量

所有资源数据也可通过工具访问。

功能参考

wikidata_search_entities _工具

• 搜索标签、别名和描述；type="item" 用于人物、地点和作品，type="property" 用于 P-ID
• 接受 Wikidata 语言代码（en、de、pt-br；不区分大小写）；使用偏移量分页，每次调用最多返回 50 条结果
• 每条匹配结果都包含匹配元数据，说明匹配的是标签还是别名

---

wikidata_get_entity _工具

• Q-ID（例如 Q76）用于获取项目，P-ID（例如 P31）用于获取属性；fields 用于选择 labels、descriptions、aliases、statements 或 sitelinks，并缩小上游获取范围（Q76 的完整数据为 344,114 字节，仅获取 labels 时为 6,703 字节）
• languages 用于将多语言映射限制为指定的语言代码
• 如果实体太大而无法内联返回，则会返回字段类别概览及其字节大小；其 retrieval_notice 会列出适合返回的 fields 集合，并指出可用于缩小超大 statements 或 sitelinks 范围的工具

---

wikidata_get_labels _工具

• 每次调用最多通过 MediaWiki wbgetentities API 查询 50 个 ID，每个请求可指定一个或多个语言代码
• 对部分结果报告 found 数量和 notFound ID
• 用于接续 SPARQL 查询：先运行查询，再将 QID 转换为易读标签

---

wikidata_get_statements _工具

• properties 用于将获取范围限制为特定 P-ID（省略则获取全部）；值、限定符和引用中的项目 QID 与数量单位会被解析为标签，除非设置 resolve_labels=false
• 引用会按来源分组；未知或缺失值会以 somevalue / novalue 返回
• 如果 statement 集合太大而无法内联返回，则会返回按字节大小降序排列的 P-ID 概览（未筛选时，Q30 包含 467 个属性和 1,717 条 statements）；根据 retrieval_notice 的建议，使用字节大小总和不超过 24,000 的 properties 重新调用

---

wikidata_get_sitelinks _工具

• 将站点代码（例如 enwiki）映射到文章标题和 URL；sites 用于筛选特定代码
• wikis_only=true 仅保留 Wikipedia 链接（排除 Wiktionary、Wikiquote、Wikisource 等）
• 仅支持 Q-ID；不支持 P-ID

---

wikidata_sparql_query _工具

• 对 Wikidata Query Service（Blazegraph）运行 SELECT 查询；ASK、CONSTRUCT、DESCRIBE、更新操作和普通搜索文本会在发送请求前被拒绝
• 会自动添加标准前缀（wd:、wdt:、p:、ps:、pq:、wikibase:、bd:）和 wikibase:label SERVICE（当查询使用 ?<var>Label、?<var>Description 或 ?<var>AltLabel 变量时）；language 接受单个代码或备用语言列表，如 fr,en
• 结果为 SPARQL 1.1 JSON 绑定，每个响应上限为 64,000 字节，并会在完整行之间截断；结果较大时会返回开头的若干行以及 returnedCount、totalCount，并提示使用 ORDER BY 配合 LIMIT / OFFSET 分页或进行聚合
• 客户端 timeout 为 1–55s（服务端硬性上限为 60s）；速率限制为每分钟 60 个请求，每个 IP 最多 5 个并发请求

---

wikidata_resolve_external_id _工具

• 将 DOI（P356）、PMID（P698）、ORCID（P496）、OpenAlex ID（P10283）、IMDb ID（P345）和其他外部 ID 解析为 QID；会去除空白字符和解析器 URL 前缀，并对 DOI、PMID 和 ORCID 进行规范化
• 属性的数据类型必须是 external-id；不接受项目值属性或媒体属性（例如 P31、P18）
• 未找到时返回 match=null（Query Service 与实时 wiki 存在延迟，因此 null 不能证明目标不存在）；当多个实体声明了同一 ID 时返回 multipleMatches；标签使用请求的 language，找不到时回退到 mul

---

wikidata://entity/{id} _资源

• 紧凑的 Markdown 摘要 — 标签（所有语言）、英文描述、instance-of（P31）、enwiki Wikipedia 链接、图片（P18）和 statement 数量
• 以 text/markdown 格式返回；如需完整实体数据，请使用 wikidata_get_entity
• id 为 Q-ID 或 P-ID，与工具接受的标识符相同

功能

基于 @cyanheads/mcp-ts-core 构建：支持 stdio 和 Streamable HTTP 传输、可插拔身份验证（none / jwt / oauth）、可切换存储（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1），并提供结构化日志记录和可选的 OpenTelemetry 链路追踪。

Wikidata 专属功能：

• 使用 Wikidata REST API v1 获取实体和声明；查找操作无需承担 SPARQL 开销
• 使用 MediaWiki wbgetentities API，高效批量解析标签
• 使用 Wikidata Query Service（Blazegraph）执行 SPARQL，并自动注入前缀标头和标签 SERVICE
• 按照 Wikimedia 政策配置 User-Agent（WIKIDATA_USER_AGENT）
• 为 REST 和 SPARQL 端点分别配置超时（WIKIDATA_REST_TIMEOUT_MS、WIKIDATA_SPARQL_TIMEOUT_MS）

适用于 Agent 的输出：

• 所有工具都会在响应中回显相关输入参数，以便追踪
• wikidata_get_labels 专为处理 SPARQL 结果集而设计：先运行查询，再通过一次调用将结果转换为易读形式
• 如果 Wikidata 数据完整性问题导致某个外部 ID 存在重复声明，wikidata_resolve_external_id 会返回 multipleMatches，而不是错误地返回 null
• 实体和声明集过大时，会返回 kind: "outline" 负载，其中包含字段／属性大小以及列出确切重新调用方式的 retrieval_notice，而不是返回截断或过大的响应

开始使用

公共托管实例

公共实例可通过 https://wikidata.caseyjhand.com/mcp 使用，无需安装。该实例提供 Streamable HTTP；每个客户端的配置格式各不相同。

对于 Claude Code：

claude mcp add --transport http wikidata-mcp-server https://wikidata.caseyjhand.com/mcp

对于 Cline（cline_mcp_settings.json）：

{
  "mcpServers": {
    "wikidata-mcp-server": {
      "type": "streamableHttp",
      "url": "https://wikidata.caseyjhand.com/mcp"
    }
  }
}

对于 Cursor（mcp.json）：

{
  "mcpServers": {
    "wikidata-mcp-server": {
      "url": "https://wikidata.caseyjhand.com/mcp"
    }
  }
}

Claude Desktop 可在 Settings → Connectors 中添加远程服务。

自托管／本地运行

将以下内容添加到 MCP 客户端配置文件中。

{
  "mcpServers": {
    "wikidata-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/wikidata-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

也可以使用 npx（无需 Bun）：

{
  "mcpServers": {
    "wikidata-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/wikidata-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

也可以使用 Docker：

{
  "mcpServers": {
    "wikidata-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/wikidata-mcp-server:latest"]
    }
  }
}

若要使用 Streamable HTTP，请设置传输方式并启动服务：

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

前置条件

• Bun v1.4.0 或更高版本（或 Node.js ≥ 24.0.0）。

安装

1. 克隆仓库：

git clone https://github.com/cyanheads/wikidata-mcp-server.git

2. 进入目录：

cd wikidata-mcp-server

3. 安装依赖项：

bun install

4. 配置环境：

cp .env.example .env
# edit .env and set any overrides

配置

所有配置都会在启动时通过 Zod 模式进行验证。主要环境变量：

变量	描述	默认值
MCP_TRANSPORT_TYPE	传输方式：stdio 或 http	stdio
MCP_HTTP_PORT	HTTP 服务端口	3010
MCP_HTTP_ENDPOINT_PATH	MCP 服务挂载的 HTTP 端点路径	/mcp
MCP_PUBLIC_URL	用于 TLS 终止反向代理部署的公共源覆盖值	无
MCP_AUTH_MODE	身份验证：none、jwt 或 oauth	none
MCP_SESSION_MODE	HTTP 会话模式：stateful、stateless 或 auto	stateless
MCP_LOG_LEVEL	日志级别（debug、info、notice、warning、error）	info
MCP_GC_PRESSURE_INTERVAL_MS	可选启用的强制 GC 间隔，单位为 ms（仅 Bun）	0（已禁用）
LOGS_DIR	日志文件目录（仅 Node.js）	<project-root>/logs
STORAGE_PROVIDER_TYPE	存储后端：in-memory、filesystem、supabase、cloudflare-kv/r2/d1	in-memory
WIKIDATA_USER_AGENT	Wikimedia 请求使用的 User-Agent 字符串（政策要求提供描述性值）	wikidata-mcp-server/0.1 (https://github.com/cyanheads/wikidata-mcp-server)
WIKIDATA_SPARQL_TIMEOUT_MS	等待 SPARQL 响应的最长时间，单位为 ms	55000
WIKIDATA_REST_TIMEOUT_MS	等待 REST API 响应的最长时间，单位为 ms	10000
OTEL_ENABLED	启用 OpenTelemetry	false

完整的可选覆盖项列表请参阅 .env.example。

运行服务

本地开发

• 构建并运行生产版本：

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:http
  # or
  bun run start:stdio
  

• 运行检查和测试：

  bun run devcheck  # Lints, formats, type-checks, and more
  bun run test      # Runs the test suite
  

Docker

docker build -t wikidata-mcp-server .
docker run --rm -p 3010:3010 wikidata-mcp-server

Dockerfile 默认使用 HTTP 传输、无状态会话模式，并将日志写入 /var/log/wikidata-mcp-server。默认会安装 OpenTelemetry 对等依赖；构建时使用 --build-arg OTEL_ENABLED=false 可省略这些依赖。

项目结构

目录	用途
src/index.ts	createApp() 入口点——注册工具和资源，并初始化服务。
src/mcp-server/tools	工具定义（*.tool.ts）。包含用于实体查询、陈述、站点链接、SPARQL 和外部 ID 解析的七个工具。
src/mcp-server/resources	资源定义。包含实体摘要资源。
src/services/wikidata	Wikidata 服务层——REST API 客户端、SPARQL 客户端、陈述规范化和类型。
src/config	使用 Zod 解析并验证服务器专用环境变量。
tests/	单元测试和集成测试，结构与 src/ 对应。

开发指南

开发指南和架构规则请参阅 CLAUDE.md。简要说明：

• 处理程序抛出异常，框架负责捕获——工具逻辑中不要使用 try/catch
• 使用 ctx.log 记录日志，使用 ctx.state 存储数据
• 在 createApp() 数组中注册新工具和资源
• 封装外部 API 调用：验证原始数据 → 规范化为领域类型 → 返回输出架构；绝不伪造缺失字段

贡献

欢迎提交问题。提交前请运行检查和测试：

bun run devcheck
bun run test

许可证

Apache-2.0——详情请参阅 LICENSE。