geojp

geojp-mcp

点击此处查看日语版 README

一个 MCP（Model Context Protocol）服务，将两个日本专用地理数据 API 作为工具提供给 AI Agent（Claude Code、Claude Desktop 和其他 MCP 客户端）：

• ChibanJP — 坐标 → chiban（地番，即日本法务局登记的官方地籍地块号）。Chiban 很少能按可预测的方式映射到住宅地址（住居表示），而且大多数通用地理编码服务都不提供这项数据。
• ReverseGeoJP — 坐标 ⇄ 日文地址（反向地理编码 / 正向地理编码）。

为什么需要 chiban？

日本使用两套互不相关的地址系统：出现在地图和邮件上的住宅地址（住居表示），以及用于不动产登记、土地交易和法律文件的地籍地块号 chiban。两者之间没有可预测的对应规律，因此转换需要查询登记地图数据，而非查找对照表。

Chiban 对不动产尽职调查、土地交易平台以及任何涉及日本登记系统的工作流都很重要。随着外国对日本房地产的投资增加，这类需求也日益增长。大多数全球地理编码 API 不会直接从登记地图数据中获取 chiban，因此我们提供了这个独立工具。

工具

工具	后端 API	输入	返回内容
get_parcel	ChibanJP /parcel	lat、lon	所在地块的 Chiban（地籍地块号）、大字 / 字、市町村，以及测量精度等级
reverse_geocode	ReverseGeoJP /reverse	lat、lon	最近的住宅地址（都道府县、市町村、地区、邮政编码）
geocode	ReverseGeoJP /geocode	address	最多 10 个与部分地址匹配的候选位置
lookup_location	两者，并行调用	lat、lon	一次调用同时获取地址和 chiban（编排示例 — 如果坐标不在 ChibanJP 当前覆盖范围内，则仍可返回仅含地址的结果）

所有工具共用一个 API 密钥。请前往 reversegeojp.com 获取。

两种运行方式

工具定义位于 src/tools.ts，供两个入口共享：

• 本地（stdio） — src/index.ts。MCP 客户端会在你的计算机上将其作为子进程启动。适用于单个用户和一个 API 密钥。
• 远程（HTTP，Cloudflare Workers） — src/worker.ts。已部署至 https://mcp.reversegeojp.com；任何人都可以使用自己的 API 密钥连接，无需构建。

设置（本地 / stdio）

npm install -g geojp-mcp

或从源代码安装：

npm install
npm run build

服务从 GEOJP_API_KEY 环境变量读取 API 密钥。通常你不需要直接运行它 — MCP 客户端会将其作为子进程启动（见下文）。

注册到 Claude Code

claude mcp add --scope user geojp -e GEOJP_API_KEY=your-api-key-here -- npx geojp-mcp

--scope user 会使其在你计算机上的所有项目中可用（省略该参数即可仅为当前项目注册）。使用 claude mcp list 验证。

参数顺序很重要：-e/--env 可接受多个值，因此如果将其放在服务名称之前，它会吞掉后续参数。请保持以下顺序：先输入 add，再输入服务名称，然后输入 -e。

也可以在 .mcp.json / ~/.claude.json 中手动配置：

{
  "mcpServers": {
    "geojp": {
      "type": "stdio",
      "command": "npx",
      "args": ["geojp-mcp"],
      "env": {
        "GEOJP_API_KEY": "your-api-key-here"
      }
    }
  }
}

注册到 Claude Desktop

将相同的配置块添加到 claude_desktop_config.json 的 mcpServers 部分，然后重启 Claude Desktop。届时即可使用四个工具（reverse_geocode、geocode、get_parcel、lookup_location）。

设置（远程 / HTTP）

使用你自己的 API 密钥直接连接到托管服务 — 无需安装或构建：

claude mcp add --scope user --transport http geojp-remote https://mcp.reversegeojp.com --header "Authorization: Bearer your-api-key-here"

健康检查：GET https://mcp.reversegeojp.com/health。

远程服务设计说明

• 无绑定、无状态：Worker 不保存会话状态，也不使用 Durable Objects。每次调用都会从 Authorization 标头读取 API 密钥，并直接代理到 ReverseGeoJP/ChibanJP 生产 API。这样就不需要 Durable Objects 所要求的付费 Workers 计划，因此可以像 reverse-geo-jp/chibanjp 一样运行在免费计划上，不增加基础设施成本（更常见的 agents-sdk 中的 McpAgent 模式需要 Durable Objects 和付费计划）。
• Web 标准传输：使用 @modelcontextprotocol/sdk 的 WebStandardStreamableHTTPServerTransport，因为仅适用于 Node.js 的 StreamableHTTPServerTransport 依赖 http.IncomingMessage/ServerResponse，而它们在 Workers 运行时中不存在。
• 注意事项：reversegeojp-client/chibanjp-client 默认会保存一个未绑定的 fetch（this.fetchImpl = options.fetch ?? fetch），这在 Cloudflare Workers 上会抛出 "Illegal invocation"。已通过在 createGeojpMcpServer() 的客户端构造选项中传入显式绑定的 fetch 修复（参见 src/tools.ts 中的 boundFetch）。此问题也已在上游 geojp-api-clients v0.1.1 中修复（fetch.bind(globalThis)）；geojp-mcp 依赖该版本，并保留本地的 boundFetch 作为无害的备用方案。

部署 / 本地开发

npm run worker:dev     # local wrangler dev server (http://127.0.0.1:8787 etc.)
npm run worker:check   # typecheck against the Workers tsconfig only
npm run worker:deploy  # deploy to production

冒烟测试（无需 API 密钥——仅检查连接配置）

npm run smoke-test

使用虚拟密钥启动服务，确认工具列表可以加载，并且真实 API 调用会正确返回 invalid_api_key 错误。

项目缘起

ReverseGeoJP/ChibanJP 已作为 API 运行，供阅读文档的开发者直接调用。本项目将它们作为 MCP 工具开放，让 AI Agent 能够自动发现并调用这些工具——复用现有生产基础设施，同时积累 MCP/Agent 集成的实践经验。

许可证

MIT