JP Data (Japanese Public Business Data)

jp-data-mcp — 面向 AI Agent 的日本公共商业数据

一个免费、开源的 MCP 服务，为 AI Agent 提供最常用的日本商业数据基础功能：

• 法人番号 — 离线校验校验位；提供（免费）国税厅应用 ID 后，可通过国税厅 法人番号 Web-API 获取实时登记信息：登记名称、地址、实体类型和日期。
• 全银银行／分行代码（統一金融機関コード・支店コード） — 用于描述日本国内银行转账的代码，包含假名／平假名／罗马字。
• 日本法定节假日 — 内置内阁府官方节假日数据。

完全在你的机器上运行。无需账户、无需我们的 API 密钥、无需付费、无遥测——不会在任何地方记录或报告使用情况。

工具

工具	功能
validate_corporate_number	离线格式校验 + 国税厅官方校验位校验，适用于 13 位法人番号（可接受全角输入）。不会确认公司是否存在。
lookup_corporate_number	查询法人番号的登记信息（设置 NTA_APP_ID 时使用国税厅实时 Web-API；否则使用明确标记的合成备用数据——见下文）。
search_corporations_by_name	按名称（部分匹配）搜索法人（设置 NTA_APP_ID 时使用国税厅实时 Web-API）。
lookup_bank	按 4 位全银银行代码查询银行 → 名称／假名／平假名／罗马字。
search_banks	按名称片段搜索银行（汉字／假名／平假名／罗马字）。
lookup_branch	按银行代码 + 3 位分行代码查询分行（按需从公开的全银代码数据集获取分行数据，并在本地缓存）。
japan_holidays	查询指定年份的所有日本法定节假日。
is_japan_holiday	查询 YYYY-MM-DD 日期是否为法定节假日。

重要提示：SYNTHETIC_SAMPLE 备用数据

实时法人登记数据需要免费的国税厅 Web-API 应用 ID （在国税厅 法人番号系统 Web-API 网站注册）， 并通过 NTA_APP_ID 环境变量提供。

未设置 NTA_APP_ID 时，lookup_corporate_number 和 search_corporations_by_name 会改用一小组内置的合成示例数据。 这些记录是为测试而虚构的，不对应真实公司，并且每条记录都带有 "source": "SYNTHETIC_SAMPLE" 标记，响应中还包含说明性的 note——绝不会被误认为真实登记数据。校验位验证以及银行／节假日工具无需任何密钥，始终使用真实数据。

已知限制：NTA v4 CSV 列映射依据已发布的规范编写，但尚未通过实时 API 响应验证。如果你发现字段错位，请提交 issue。

安装与运行

需要 Python 3.11+。

git clone https://github.com/kimotostudio/jp-data-mcp.git
cd jp-data-mcp
pip install fastmcp httpx    # or: uv sync
python src/server.py         # stdio MCP server

也可以使用 uv，无需显式安装步骤：

uv run --directory /path/to/jp-data-mcp src/server.py

Claude Desktop／MCP 客户端配置（stdio）

{
  "mcpServers": {
    "jp-data": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/jp-data-mcp", "src/server.py"],
      "env": { "NTA_APP_ID": "your-nta-app-id (optional)" }
    }
  }
}

每个 GitHub release 都附有一个 .mcpb bundle（可供兼容 MCPB 的客户端使用）。

本地 HTTP 模式（可选）

python src/server.py --http   # streamable-http on 127.0.0.1:8765 (localhost only)

测试

python test_client.py

数据来源与许可证

数据	来源	条款
法人登记	国税厅 法人番号系统 Web-API v4（实时数据，仅在配置你自己的 NTA_APP_ID 时使用）	使用时须遵守国税厅 Web-API 使用条款
校验位公式	国税厅官方规范（离线实现）	—
银行／分行代码	zengin-code/source-data（内置银行列表；按需获取分行文件）	MIT 许可证
法定节假日	内阁府 国民の祝日 CSV（内置，已转换为 UTF-8）	日本政府开放数据
合成法人示例	为本项目生成（校验位有效，虚构公司）	MIT（本仓库的一部分）

免责声明

本项目与日本国税厅、日本银行家协会、zengin-code 项目或内阁府均无关联，也未获得其认可。数据按「原样」提供，不保证准确性或完整性；在将其用于法律、税务、会计或支付决策之前，请对照官方来源进行核实。随附的数据集为快照，可能滞后于官方来源。

许可证

MIT