mcp-docs-server

Mapbox MCP 文档服务

一个 模型上下文协议（MCP） 服务，让 AI 助手即时访问 Mapbox 文档和参考资料——无需 Mapbox 访问令牌。

快速开始

托管服务（无需安装）

直接连接到托管端点——无需安装或维护：

Claude Code / Claude Desktop / Cursor / VS Code

{
  "mcpServers": {
    "mapbox-docs": {
      "url": "https://mcp-docs.mapbox.com/mcp"
    }
  }
}

---

npx（在本地运行，无需安装）

Claude Code — 运行 claude mcp add：

claude mcp add mapbox-docs -- npx -y @mapbox/mcp-docs-server

Claude Desktop — 添加到 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）：

{
  "mcpServers": {
    "mapbox-docs": {
      "command": "npx",
      "args": ["-y", "@mapbox/mcp-docs-server"]
    }
  }
}

Cursor / VS Code — 将相同的 mcpServers 配置块添加到编辑器的 MCP 设置文件中。

---

Docker

构建镜像：

docker build -t mapbox/mcp-docs-server .

或从注册表拉取：

docker pull mapbox/mcp-docs-server

Claude Desktop / Cursor / VS Code — 将 MCP 客户端配置为运行容器：

{
  "mcpServers": {
    "mapbox-docs": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "mapbox/mcp-docs-server"]
    }
  }
}

---

本地（从源代码运行）

git clone https://github.com/mapbox/mcp-docs-server.git
cd mcp-docs-server
npm install
npm run build

Claude Desktop / Cursor / VS Code：

{
  "mcpServers": {
    "mapbox-docs": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-docs-server/dist/esm/index.js"]
    }
  }
}

工具

get_document_tool — 根据 URL 获取指定 Mapbox 文档页面的完整内容。可用于打开资源中的链接并获取完整页面内容。

提示词示例：

• “有哪些 Mapbox API 可用？”
• “如何向 Mapbox 样式添加自定义图层？”
• “最新的 Mapbox GL JS 版本是什么？”

batch_get_documents_tool — 一次调用即可获取多个 Mapbox 文档页面（最多 20 个）。比多次调用 get_document_tool 更高效。获取失败的页面会包含错误消息，不会导致整个批次失败。

search_mapbox_docs_tool — 搜索 Mapbox 文档，涵盖 API 参考、GL JS、帮助中心、Style Spec、Studio、Search JS、iOS/Android Maps 和 Navigation SDK，以及 Tilesets，并返回排名后的页面 URL 和描述。使用此工具可先查找相关文档，再通过 get_document_tool 或 batch_get_documents_tool 获取完整页面。

提示词示例：

• “查找有关摄像机动画的文档”
• “搜索地理编码 API 示例”
• “有哪些关于自定义图层的文档？”

资源

MCP 资源提供参考数据，AI 助手可按需读取：

资源 URI	内容
resource://mapbox-api-reference	REST API 参考文档（端点、参数、速率限制）
resource://mapbox-sdk-docs	SDK 和客户端库文档（iOS、Android、Flutter、Web）
resource://mapbox-guides	教程、操作指南和指南
resource://mapbox-examples	代码示例、API 互动体验和交互式演示
resource://mapbox-reference	Tilesets、数据产品、账户和定价参考
resource://mapbox-style-layers	样式图层参考（所有图层类型的 paint/layout 属性）
resource://mapbox-streets-v8-fields	Mapbox Streets v8 tileset 字段参考
resource://mapbox-token-scopes	所有可用的 Mapbox 令牌范围及其说明
resource://mapbox-layer-type-mapping	Mapbox 图层类型与其属性的映射

开发

先决条件

• Node.js >= 22
• npm

设置

git clone https://github.com/mapbox/mcp-docs-server.git
cd mcp-docs-server
npm install

命令

npm run build          # Compile TypeScript (ESM + CJS)
npm test               # Run test suite (vitest)
npm run lint           # ESLint
npm run format         # Prettier check
npm run format:fix     # Prettier auto-fix
npm run inspect:build  # Launch MCP Inspector against built server
npm run inspect:dev    # Launch MCP Inspector against source (tsx)

架构

该服务是一个 TypeScript MCP 服务，使用 @modelcontextprotocol/sdk，并通过 tshy 构建 ESM/CJS 双格式版本。

• 工具在 src/tools/ 中扩展 BaseTool<InputSchema, OutputSchema>
• 资源在 src/resources/ 中扩展 BaseResource
• 文档工具无需 Mapbox 访问令牌
• HTTP 请求使用共享的 httpPipeline，缓存时长为 1 小时

创建新工具

1. 创建目录 src/tools/my-tool/
2. 添加 MyTool.input.schema.ts（Zod 模式）、MyTool.output.schema.ts 和 MyTool.ts（继承 BaseTool）
3. 在 src/tools/toolRegistry.ts 中注册
4. 在 test/tools/my-tool/ 中添加测试

贡献

提交拉取请求前，请阅读 CONTRIBUTING.md 和 VISION.md。使用 AI 编码助手的贡献者还应阅读：

• CLAUDE.md — 适用于 Claude Code
• AGENTS.md — 适用于其他 AI 编码助手（Cursor、Copilot、Aider 等）

许可证

MIT — 请参阅 LICENSE