wikipedia-mcp-server

---

概述

任意语言版本的维基百科。搜索文章、阅读摘要或所需章节、查找坐标附近带地理标签的页面，以及列出文章的语言版本。

工具

工具	描述
wikipedia_search_articles	在维基百科中进行全文搜索，返回按相关性排序的结果，其中包括简短描述、Wikidata QID、纯文本摘要和页面 ID，以及维基百科提供的拼写建议。
wikipedia_get_summary	获取任意文章的简短摘要——纯文本、Wikidata QID、描述、缩略图 URL、页面类型、规范 URL、修订版本和坐标。
wikipedia_get_article	以整洁的纯文本形式获取完整文章或指定章节，并保留章节标记，同时提供规范 URL 和读取内容所用的修订版本。
wikipedia_get_sections	获取目录，其中包含用于读取指定章节的 section_index 值。
wikipedia_search_nearby	查找 WGS 84 坐标一定半径内带地理标签的维基百科文章，按距离排序，并提供简短描述和 Wikidata QID。
wikipedia_get_languages	获取某篇文章的所有语言版本及其标题和 URL，也可以只获取指定版本。

功能参考

wikipedia_search_articles _工具

• 自由文本 query（为空时会报错 empty_query）、正整数 limit（默认值为 10，上限为 50）以及用于分页的 offset，并返回补充信息 nextOffset。只有被限制上限的调用才会包含 requestedLimit、appliedLimit 和上限提示。Wikipedia 不会提供第 10,000 条之后的结果：offset 达到或超过该位置时会报错 offset_too_large，而以该位置为结尾的页面会带有补充信息 truncated
• CirrusSearch 运算符包括 incategory:"1648 treaties"、morelike:Peace of Westphalia、intitle:Python、hastemplate:Infobox 和 insource:Python（支持情况取决于安装环境）。sort 默认值为 relevance；其他选项有 last_edit_desc、create_timestamp_desc、incoming_links_desc 和 title_natural_asc。补充信息会回显 sort；分页时请保持 sort 和 query 不变
• 每条结果都包含纯文本摘要、页面 ID、字数，以及文章有这些信息时的简短 description 和 Wikidata QID（wikibase_item）；补充信息 suggestion 会提供 Wikipedia 的拼写修正（einstien → einstein）
• 无效或过于复杂的 insource:/…/ 和 intitle:/…/ 正则表达式只会报错一次，并返回 invalid_query、upstreamCode，以及修正或简化正则表达式、或移除运算符的指引。繁忙时的正则搜索仍可重试

---

wikipedia_get_summary _工具

• 接受 title；返回 REST 摘要摘录——即导语开头的一段内容（使用 wikipedia_get_article 和 section_index: 0 可读取完整导语）——以及简短描述、缩略图 URL、Wikidata QID（wikibase_item），对于带地理标签的文章，还会返回可直接传给 wikipedia_search_nearby 的 latitude / longitude
• page_type 用于区分 standard / disambiguation / no-extract（对于 disambiguation，请使用 wikipedia_search_articles 重新查询）；url、revision_id 和 last_modified 指明读取的修订版本，?oldid=<revision_id> 是该版本的永久链接
• 已存在但没有摘要摘录的页面会成功返回元数据、空的 extract，以及打开规范 URL 或尝试 section_index: 0 的指引。命名空间页面可能包含文档，而非文章正文。空的描述会被省略；缺少标题时仍会报错 not_found

---

wikipedia_get_article _工具

• 不提供 section_index：返回包含 == Section == 标记的完整文章；若超过 WIKIPEDIA_ARTICLE_OVERFLOW_BYTES（默认 80,000 字节），则返回章节大纲（truncated: true）。提供从 wikipedia_get_sections 获取的 section_index（0 为导语）：返回该章节及其嵌套子章节
• 大纲条目会在可用时包含经过验证的 section_index 值，包括导语的 0。含义模糊或未编入索引的标题会保留章节列表中的备用项。目录验证会进行一次简短尝试；若无法验证，会明确说明
• 重定向会提供 redirected_from；对于章节目标，还会提供 redirect_section。完整读取仍会返回完整内容，并包含针对性读取的说明；显式指定的 section_index（包括 0）优先
• 每次读取都会返回 url 和 revision_id（?oldid=<revision_id> 是所读文本的永久链接）；完整读取（包括大纲）还会返回 last_modified。设置 WIKIPEDIA_BASE_URL 后，章节读取不会提供 url
• 章节读取会将系统发育支系树渲染为带缩进的分支代码块，将每行标签与其叶节点配对，并保留未命名的分叉。无法解析的树会留下 [table omitted: unparseable clade]；树没有 table_index
• 章节读取还会将数据表以竖线分隔的行呈现，并将信息框以 标签: 值 的形式呈现；完整文章提取会剔除这些内容。渲染后超过 40,000 字节的表格会留下 [table omitted: N rows (table T)] 标记。将 table_index: T 与章节一起传入，即可按完整行分页读取该表；随后将 next_cursor 作为 cursor，并使用相同输入继续读取。后续页会读取第一页对应的修订版本；标题和表头仅显示一次。每页表格文本在两种界面上均不超过 40,000 UTF-8 字节，但不可拆分的超大行，或单独返回的首页标题／表头除外；此时会设置 oversized_row: true

---

wikipedia_get_sections _工具

• 接受 title；返回章节标题、标题级别、层级编号（例如 "2.1"）以及传给 wikipedia_get_article 的 section_index——第一项为导语（index: 0，标题为 Introduction）
• 标题会按照文章渲染器的规则进行文字脚本、公式、空白字符和单次实体规范化处理，因此 CO₂ 在章节列表、文章读取结果和经过验证的大纲条目中保持一致
• 对于短篇或极短文章，会以 no_sections 失败；请改用 wikipedia_get_article 读取
• 重定向别名会提供 redirected_from 和可选的 redirect_section；只有当唯一锚点与真实的数字目录索引匹配时，才会出现 redirect_section_index

---

wikipedia_search_nearby _工具

• latitude 为 −90…90／longitude 为 −180…180（WGS 84），radius_meters 为 10–10,000（默认 1000），limit 为正整数（默认 10，最多为 500）；超过 limit 不会分页。补充结果中的 truncated 标记表示匹配项数量超过 limit；达到 Wikipedia 上限 500 时，请改用更小的半径进行搜索。只有经截断的调用才会包含 requestedLimit、appliedLimit 和上限提示
• 返回按 distance_meters 排序的文章，包含坐标、简短的 description 和 Wikidata QID（wikibase_item）。每篇文章的位置依据文章自身的 GeoData 坐标标签，而非其 Wikidata 条目中的坐标；因此，坐标标签有误的文章会出现在标签所指的位置

---

wikipedia_get_languages _工具

• 接受 title；返回各语言版本的 language_code、edition_code、文章标题和 URL，以及解析后的标题 source_title。在其他工具中，将 edition_code（而非 language_code）作为 language 传入；两者可能不同（gsw 与 als）
• editions 会将列表缩小到指定代码：没有对应文章的代码会列在 missing 下，total_languages 仍为未筛选的总数。文章没有其他语言译本时会以 no_other_languages 失败；筛选条件没有匹配项时则返回空列表，而不会失败

功能

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

Wikipedia 专属功能：

• 双 API 集成——MediaWiki REST API（/api/rest_v1/）用于摘要，Action API（/w/api.php）用于搜索、全文、章节、地理搜索和语言链接
• 所有必需请求均支持重试和退避，包括 Action API 在 HTTP 200 响应正文中返回的临时拒绝（搜索过于繁忙、请求受限、只读）；遵循上游的 Retry-After，且每个请求的重试时间上限为 30 s。搜索结果中的尽力而为描述查询只进行一次短暂尝试；根据 Wikimedia API 政策设置 User-Agent 请求头
• 所有读取路径都通过同一个渲染器将 HTML 转换为统一的纯文本格式——== Heading == 标记、每行一个列表项、保留上标、代码块使用围栏标记：Action API 的 HTML 摘录提供完整文章，解析器为相应章节提供的 HTML 提供章节内容，REST extract_html 提供摘要。章节读取还会包含数据表、信息框以及布局表格中的列表，这些内容不会包含在摘录中
• 每个工具都支持单次调用的 language 参数（默认值为 en）——可在同一会话中访问所有 Wikipedia 语言版本；读取标题时都会遵循重定向
• 根据 MediaWiki action=sitematrix 端点构建实时版本注册表并验证语言（缓存 24h）——可在导致超时之前捕获格式有效但实际不存在的版本

便于 Agent 使用的输出：

• 摘要中的 page_type 可区分 standard / disambiguation / no-extract——无需解析字符串
• 摘要、搜索结果和附近结果中的 wikibase_item（Wikidata QID）支持直接与 wikidata-mcp-server 交叉引用
• 文章文本、摘要片段和标题在进入 markdown content[] 渲染时会进行反斜杠转义，因此介绍标记语言或 Markdown 语法的文章会按原文显示，而不会被客户端解析；structuredContent 携带相同的未转义文本。围栏代码块和表格行分隔符不转义，表格单元格仍会转义
• 目录条目中的 section_index 可直接关联到 wikipedia_get_article 的定向读取参数，包括索引 0
• 对于 MediaWiki 无法用于页面命名的标题——< > [ ] { }、| 多标题分隔符、百分号转义、魔法波浪号、相对路径——会在发出任何请求前拒绝，并返回 invalid_title；尾随的 #fragment 可以接受并正常解析
• 每种错误类型都提供恢复提示——调用方可以获得可执行的后续步骤（例如，“使用 wikipedia_search_articles 查找正确标题”）

开始使用

公共托管实例

可通过 https://wikipedia.caseyjhand.com/mcp 使用公共实例——无需安装。通过 Streamable HTTP 将任意 MCP 客户端指向该实例：

{
  "mcpServers": {
    "wikipedia-mcp-server": {
      "type": "streamable-http",
      "url": "https://wikipedia.caseyjhand.com/mcp"
    }
  }
}

自托管 / 本地

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

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

或者使用 npx（无需 Bun）：

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

或者使用 Docker：

{
  "mcpServers": {
    "wikipedia-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT_TYPE=stdio",
        "ghcr.io/cyanheads/wikipedia-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 v24+）。
• 无需 API 密钥——Wikipedia API 是公开的。

安装

1. 克隆仓库：

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

2. 进入目录：

cd wikipedia-mcp-server

3. 安装依赖项：

bun install

4. 配置环境（可选）：

cp .env.example .env
# edit .env if you want to customize WIKIPEDIA_USER_AGENT or logging

配置

变量	描述	默认值
WIKIPEDIA_USER_AGENT	每次 Wikimedia API 请求都会发送的 User-Agent 标头。可根据部署情况自定义。	wikipedia-mcp-server/0.2.8 (https://github.com/cyanheads/wikipedia-mcp-server)
WIKIPEDIA_BASE_URL	可选的单实例覆盖设置。未设置（默认）：按语言组合主机，每次调用时由 language 选择对应版本。设置为完整的基础 URL（例如私有 MediaWiki 镜像）：所有调用都路由到同一个固定主机，language 不再改变主机。	(未设置)
WIKIPEDIA_ARTICLE_OVERFLOW_BYTES	完整文章读取（wikipedia_get_article 未指定 section_index）超过此字节数时，将返回章节大纲而非全文。此值针对该领域进行了调整：普通文章会完整返回；只有真正的超长文章（第二次世界大战约 86 KB，美国约 94 KB）会返回大纲。按章节读取不受影响。	80000
MCP_TRANSPORT_TYPE	传输方式：stdio 或 http。	stdio
MCP_HTTP_PORT	HTTP 服务端口。	3010
MCP_SESSION_MODE	HTTP 会话模式：stateless、stateful 或 auto（解析为 stateful）。Docker 镜像使用 stateless。	auto
MCP_AUTH_MODE	身份验证模式：none、jwt 或 oauth。	none
MCP_LOG_LEVEL	日志级别（RFC 5424）。	info
LOGS_DIR	日志文件目录（仅 Node.js）。	<project-root>/logs
LOG_TOOL_FAILURE_PAYLOADS	记录每次失败的工具调用参数和结果；按键名对内容进行脱敏，并限制在 LOG_TOOL_FAILURE_PAYLOAD_MAX_BYTES 字节以内（默认 16384）。自由格式值中的密钥不会被脱敏。	false
OTEL_ENABLED	启用 OpenTelemetry 插桩（跟踪跨度、指标、完成日志）。	false

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

运行服务

本地开发

• 构建并运行：

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

• 运行检查和测试：

  bun run devcheck   # Lint, format, typecheck, security
  bun run test       # Vitest test suite
  bun run lint:mcp   # Validate MCP definitions against spec
  

Docker

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

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

项目结构

目录	用途
src/index.ts	createApp() 入口点 — 注册工具并初始化 Wikipedia 服务。
src/config	使用 Zod 解析并验证服务专属的环境变量。
src/mcp-server/tools	工具定义（*.tool.ts）——每个工具对应一个文件。
src/services/wikipedia	WikipediaService——REST API 与 Action API 客户端，包含重试、退避和语言验证。
tests/	单元测试和集成测试，与 src/ 中的结构对应。

开发指南

开发指南和架构规则请参阅 CLAUDE.md。简要概述如下：

• 处理器抛出异常，框架负责捕获——工具逻辑中不要使用 try/catch
• 使用 ctx.log 进行请求范围内的日志记录，使用 ctx.state 进行租户范围内的存储
• 在 src/mcp-server/tools/definitions/index.ts 中注册新工具
• 封装外部 API 调用：验证原始数据 → 规范化为领域类型 → 返回输出架构；绝不伪造缺失字段

贡献

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

bun run devcheck
bun run test

许可证

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