12306-mcp 使用指南：用 npx 跑通 MCP 服务并接入高德地图 API

1. 从零跑通 12306-mcpnpx 启动、凭证配置与高德地图可视化12306-mcp 是一个把铁路票务查询能力封装成 MCPModel Control Protocol协议的开源组件简单说就是让 AI 助手能直接查车次、查余票、查途经站点。它适合三类人想给智能出行助手加铁路数据的开发者、做差旅管理工具的产品同学、以及想用自然语言查票的普通用户。你不需要自己爬接口只要用 npx 把服务拉起来再在支持 MCP 的客户端里配一段 JSON就能用「帮我查 5 月 20 号苏州北到青岛的余票」这种话完成查询。这篇指南聚焦完整链路npx 启动 MCP 服务、配置 API 凭证、对接高德地图做行程可视化每一步都给可复制的命令和配置片段最后附一次从查车次到地图展示的验证动作。我试过在 Cursor 里跑通整套流程踩过的坑会写在排障章节里。先说清楚 12306-mcp 能做什么。它暴露的工具包括get-stations-code-in-city按城市名查所有车站代码、get-station-code-of-city按城市名查唯一车站代码、get-station-code-by-name按车站名查代码、get-station-by-telecode按电报码查车站信息、get-tickets查余票、get-train-route-stations查列车途经站点。这些工具通过 MCP 协议注册后AI 客户端就能按需调用。你不需要记这些函数名客户端会自动根据你的自然语言选择工具但了解它们能帮你判断「为什么我的问题没被正确响应」。整个链路分四段第一段用 npx 把 12306-mcp 服务跑起来确认它能独立工作第二段在 MCP 客户端里配置服务让 AI 能调用第三段接入高德地图 API把途经站点画到地图上第四段做一次端到端验证。下面逐段展开。2. 前置准备npx 环境与 TaoToken 凭证配置在跑 12306-mcp 之前你需要两样东西一个能执行 npx 的 Node.js 环境以及一个能调用大模型的 API 凭证。npx 是 Node.js 自带的包执行器只要装了 Node.js 16 以上版本就有。检查命令node -v npx -v如果两条命令都能输出版本号环境就绪。如果提示 command not found去 Node.js 官网下载 LTS 版本安装即可。这一步没有坑装完重开终端就行。第二样是模型 API 凭证。12306-mcp 本身只负责查铁路数据它不包含大模型能力。你需要一个能调用模型的入口让 AI 理解你的自然语言并决定调用哪个 MCP 工具。这里用 TaoToken 作为模型接入层它提供兼容 OpenAI 格式的 API配置简单。访问 https://taotoken.net/api 可以拿到 API 地址在 https://taotoken.net/api-keys 生成你的 Key。拿到之后记下两个值Base URL 和 API Key后面配置客户端要用。为什么需要模型凭证因为 MCP 的工作模式是你的自然语言 → 大模型解析意图 → 模型决定调用哪个 MCP 工具 → 工具返回数据 → 模型组织成回答。没有模型MCP 工具就是一堆没人调用的函数。所以凭证配置是链路里不可跳过的一环。如果你用的是 Claude Code 这类工具凭证配置方式略有不同。Claude Code 通过环境变量或配置文件读取模型信息具体可以看 https://taotoken.net/doc 的接入文档。核心是三件套Base URL、API Key、Model ID。Model ID 填你套餐里支持的模型名比如claude-sonnet-4-20250514这类。三个值缺一不可少一个就会报 401 或 model not found。准备好这两样后进入下一段实际配置。3. 可复制配置mcp.json 与高德地图 API 接入这一段给完整可复制的配置片段。先配 12306-mcp 服务本身。在 Cursor 里打开 Cursor Settings找到 MCP 选项卡点右上角 Add new global MCP server会自动打开mcp.json文件。把下面这段粘进去{ mcpServers: { 12306-mcp: { command: npx, args: [-y, 12306-mcp] } } }注意mcpServers下面这个 key 名12306-mcp是服务标识你可以改成别的名字但后面引用时要一致。command是npxargs里-y表示自动确认安装12306-mcp是包名。保存后回到 MCP 页面应该能看到这个服务状态是绿色或显示已连接。如果显示红色或报错看第五段的排障。接下来配模型凭证。如果你用的是 Cursor 内置的模型可以跳过如果要接 TaoToken在 Cursor 的模型设置里填 Base URL 和 API Key。Base URL 填https://taotoken.net/apiKey 填你生成的那串。Model ID 按你套餐支持的填。这一步配好后AI 才有能力解析你的自然语言。然后配高德地图。高德地图 MCP 是另一个独立服务需要单独配置。先去高德开放平台申请一个 Web 端 JS API Key拿到后配到高德地图 MCP 服务里。配置片段类似{ mcpServers: { amap-maps: { command: npx, args: [-y, amap/amap-maps-mcp-server], env: { AMAP_MAPS_API_KEY: 你的高德Key } } } }把这段和前面的 12306-mcp 合并到同一个mcp.json的mcpServers下两个服务可以共存。合并后结构是{ mcpServers: { 12306-mcp: { command: npx, args: [-y, 12306-mcp] }, amap-maps: { command: npx, args: [-y, amap/amap-maps-mcp-server], env: { AMAP_MAPS_API_KEY: 你的高德Key } } } }保存后重启 MCP 服务或刷新页面两个服务都应该显示已连接。这里有个细节高德地图 MCP 的包名和参数可能随版本变化如果npx -y amap/amap-maps-mcp-server跑不起来去高德开放平台文档确认最新的包名。我实测时用的是这个包名能正常拉起。配置完成后你的 AI 客户端就同时具备查铁路数据和高德地图可视化的能力。下一段做实际验证。4. 验证请求从查车次到地图展示的完整动作配置好之后做一次端到端验证。打开 Cursor 的对话窗口输入我想购买2025-05-20这天从苏州北到青岛的票请帮我查询一下余票信息正常情况下AI 会调用get-tickets工具返回车次列表、出发到达时间、余票数量。如果返回的是「我没有查询铁路数据的能力」这类回答说明 MCP 服务没被正确加载回到第三段检查mcp.json是否保存、服务是否显示已连接。接着验证途经站点查询。输入请帮我查询车次G222途径站信息AI 会调用get-train-route-stations返回 G222 经过的每个站点、到达时间、停留时长。这一步验证的是工具调用链路是否通畅。最后做地图可视化。确保高德地图 MCP 已配置然后输入请将G222途径站点信息嵌入到网页中帮我生成一段高德地图JSAPI代码实现地图上标记出来途径的站点信息输出为sz.htmlAI 会结合两个 MCP 服务先用 12306-mcp 拿到 G222 的途经站点再用高德地图 MCP 生成 JSAPI 代码把站点标注到地图上。生成的文件保存为sz.html用浏览器打开应该能看到一张地图上面有 G222 途经站点的标记点。如果地图空白或报错检查高德 Key 是否有效、是否开启了 Web 端 JS API 权限。这一步是整个链路的终点也是最能体现 MCP 价值的地方你只用自然语言描述需求AI 自动编排两个服务的调用顺序最后产出一个可交互的地图页面。实测下来从输入到生成sz.html大约十几秒取决于模型响应速度。验证通过后你可以把sz.html里的 JSAPI 代码提取出来改成动态加载站点数据做成自己的行程可视化工具。核心逻辑就是调 12306-mcp 拿站点列表 → 调高德 JSAPI 画标记 → 绑定信息窗口显示到站时间。5. 常见报错排查401、local proxy failed 与 reading choices这一段列几个真实会遇到的报错和排查方法。报错一401 Unauthorized。这是模型凭证问题。检查三件套Base URL 是否填了https://taotoken.net/api注意不要多加斜杠或路径、API Key 是否复制完整前后不要有空格、Model ID 是否是套餐支持的模型名。三个值任何一个错都会 401。如果用的是 Claude Code检查~/.claude/settings.json或环境变量里的ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY是否对应。改完重启客户端。报错二local proxy failed 或 connection refused。这是 MCP 服务没起来。先手动跑一遍npx -y 12306-mcp看终端有没有报错。如果提示包不存在检查包名拼写如果提示网络超时检查网络连接。手动能跑起来但客户端里报这个错通常是客户端启动 MCP 服务时环境变量没传进去或者 npx 路径不对。在mcp.json里把command改成 npx 的绝对路径试试比如/usr/local/bin/npx。报错三reading choices 或 cannot read property of undefined。这是模型返回格式解析失败通常发生在模型返回了非预期结构时。检查 Model ID 是否填对有些模型不支持 function calling就无法驱动 MCP 工具调用。换一个支持工具调用的模型比如 Claude 系列或 GPT 系列。如果换模型后仍报错看客户端日志里模型实际返回了什么可能是 prompt 太长导致截断。报错四高德地图不显示或提示 INVALID_USER_KEY。检查高德 Key 是否绑定了正确的服务平台Web 端 JS API以及是否设置了域名白名单。本地打开sz.html时域名是file://或localhost需要在白名单里加上。如果 Key 没问题但地图仍空白打开浏览器控制台看有没有 JS 报错常见的是 JSAPI 版本号写错或 script 标签加载失败。报错五OAuth 相关错误。如果你用的是需要 OAuth 的客户端检查 token 是否过期。重新走一遍授权流程或者换成 API Key 方式接入。TaoToken 的 API Key 方式不需要 OAuth直接填 Key 即可可以避开这类问题。排查顺序建议先手动跑 MCP 服务确认能独立工作 → 再检查客户端配置 → 最后检查模型凭证。大部分问题出在第二步和第三步。6. 长期使用建议与接入入口跑通之后如果你打算长期用这套链路做编码或 Agent 任务可以考虑 Coding Plan它适合需要持续调用模型、频繁使用 MCP 工具的场景。访问 https://taotoken.net/coding-plan 看具体方案。如果只是偶尔查票、验证模型能力用模型对话入口就够了https://taotoken.net/chat。需要管理多个 Key 或查看用量去控制台https://taotoken.net/console。生成新 Key 在 https://taotoken.net/api-keys。接入文档和参数说明在 https://taotoken.net/doc。实际使用中有几个小技巧能提升体验。第一把常用的查询语句存成快捷指令比如「查明天北京到上海的余票」减少重复输入。第二如果经常查固定线路可以把站点代码缓存到本地减少get-station-code的调用次数。第三生成的地图页面可以加一个刷新按钮重新拉取最新余票数据。第四MCP 服务版本更新后npx -y会自动拉最新版如果遇到兼容问题可以锁定版本号比如12306-mcp1.0.0。最后提醒一点12306-mcp 查的是公开票务信息不涉及用户隐私数据。高德地图 API 有调用配额个人开发者的免费额度通常够用但如果要做成公开服务注意配额限制。整套链路的核心价值在于用自然语言编排多个数据源这个模式可以复制到其他场景比如查航班加地图、查天气加日历。跑通 12306-mcp 只是起点你可以按同样的方式接入更多 MCP 服务。