northdata-mcp

NorthData MCP Server

将 NorthData 公司数据 API 接入 Claude Desktop、Claude Code、Cursor 和其他 AI 助手。

Model Context Protocol（MCP）规范了大语言模型（LLM）与 NorthData 等外部服务的交互方式。此服务将 NorthData 的 suggest、search、company、person、publications、reference 和 billing 端点公开为 MCP 工具，并内置额度保护机制，防止意外产生高额费用。请参阅完整工具列表。

基于 FastMCP v3 构建。使用 stdio 传输方式——MCP 客户端会将 northdata-mcp 作为子进程启动。

---

设置

1. 阅读安全说明

运行服务前，请先浏览安全注意事项。NorthData 会按返回的公司数量收取实际费用，而 MCP 允许 LLM 自主消耗这些额度。额度保护机制可以降低风险，但纵深防御同样重要。

2. 安装服务

pipx install northdata-mcp

这会自动安装同级的 northdata-cli 软件包，并在全局公开 northdata-mcp 控制台脚本。

也可以通过 uv 安装：

uvx northdata-mcp --help

3. 获取 NorthData API 密钥

在 https://www.northdata.com 获取密钥。下一步需要将其填入 MCP 客户端配置。

可选的额度保护机制覆盖设置（在 MCP 客户端配置中设为环境变量）：

环境变量	默认值	用途
NORTHDATA_APPROVAL_THRESHOLD	25	search 的 limit 超过此值时，必须设置 approve_high_cost=true
NORTHDATA_ABSOLUTE_MAX	100	search 的 limit 硬性上限，不受标志位影响
NORTHDATA_CREDIT_LOG	~/.northdata/credits.jsonl	本地额度日志路径

4. 配置 MCP 客户端

Claude Desktop

将以下内容添加到 ~/Library/Application Support/Claude/claude_desktop_config.json （macOS）——请根据 Windows / Linux 调整路径：

{
  "mcpServers": {
    "northdata": {
      "command": "northdata-mcp",
      "env": {
        "NORTHDATA_API_KEY": "XXXX-XXXX"
      }
    }
  }
}

重启 Claude Desktop。NorthData 工具将显示在工具选择器中。

Claude Code

claude mcp add northdata --env NORTHDATA_API_KEY=XXXX-XXXX -- northdata-mcp

Cursor

将以下内容添加到 ~/.cursor/mcp.json：

{
  "mcpServers": {
    "northdata": {
      "command": "northdata-mcp",
      "env": { "NORTHDATA_API_KEY": "XXXX-XXXX" }
    }
  }
}

任意 MCP 客户端（通用）

将 northdata-mcp 作为子进程运行，并通过 stdio 使用 MCP 通信。环境中必须包含 NORTHDATA_API_KEY。

---

工具

**注意：**此服务尚未达到 1.0 版本，不同版本之间可能会有小幅破坏性变更。

每个工具都是对应 northdata-cli 命令的轻量封装。工具分为 free（不消耗额度）或 billed（消耗 NorthData 额度）两类。每个工具都设置了 MCP 注解（readOnlyHint、openWorldHint），以便行为规范的客户端在界面中显示这些信息。

免费工具

这些工具不会消耗 NorthData 额度。

• suggest — 自动补全公司或个人名称。在使用 company 或 person 消耗额度前，可先执行此操作。
• billing — 当前计费周期的远程额度使用情况（numberOfRequests、periodStart、periodEnd）。
• reference_overview — API 参考数据：标准、国家、法律形式、事件。
• reference_segment_codes — 指定标准的完整细分代码列表（默认值为 NACE2025）。
• local_credit_log — 此服务在本地维护的额度日志：总计、按月统计和逐条明细。

计费工具

以下每个工具都会消耗 NorthData 积分。NorthData 按返回的公司数量计费，而非按请求计费。积分保护机制会对 search 执行两级限额（参见积分保护）。所有计费工具都接受 dry_run=true，用于生成并返回 URL，而不消耗积分。

• search — 高级搜索。费用：最多消耗 limit 个积分。筛选条件：segment_codes、segment_standard、legal_forms、address、max_distance_km、countries、status、revenue_min/max、earnings_min/max、limit、pos、approve_high_cost。
• company — 完整公司档案（1 个积分）。通过 register（例如 HRB 123456/Muenchen）或 name + 可选的 city 进行识别。开关：owners、financials、representatives、extras、sheets、events。
• person — 人员查询（1 个积分）。返回出生日期和已知职位。接受 first_name、last_name 和可选的 city。
• publications — 公告查询（1 个积分）。通过 source="Hrb" 查询股东名单等信息。

---

积分保护

NorthData 按返回的公司数量计费。一次 limit=100 的 search 调用最多消耗 100 个积分。此服务设有两级限额：

层级	默认值	覆盖设置
审批阈值 — limit 超过此值时，必须设置 approve_high_cost=true	25	NORTHDATA_APPROVAL_THRESHOLD
绝对上限 — 硬性上限，不受 approve_high_cost 影响	100	NORTHDATA_ABSOLUTE_MAX（必须由人工显式设置，绝不能由 LLM 设置）

每次计费工具调用都会追加到本地积分日志（JSON 行格式）。local_credit_log 工具可查看该日志。日志仅供参考；billing 才是计费情况的准确信息来源。

对任何计费工具使用 dry_run=true，可在消耗积分前检查请求 URL。

---

安全注意事项

将会消耗积分的数据源连接到 LLM，既会产生实际费用，也会带来真实风险。恶意或格式错误的提示词可能导致 Agent 消耗大量积分、将结构化公司数据泄露到不可信的聊天中，或以非预期的方式将 NorthData 数据与其他工具结合使用。

建议

• 严格设置积分保护。 默认值（审批阈值为 25，绝对上限为 100）旨在防止 Agent 一次调用就耗尽积分。只有在经过审慎考虑后才提高限额。
• 探索时优先使用免费工具。 suggest、reference_* 和 billing 均免费。LLM 应先调用这些工具，再使用 company / person / publications。
• 尝试新的搜索参数或注册编号时，使用 dry_run=true。
• 审批前检查工具调用。 大多数 MCP 客户端（Claude Desktop、Cursor）都会要求你审批每次工具调用。请保持此设置开启。
• 限制每次会话的范围。 将服务交给 Agent 进行开放式工作时，请使用试用 API 密钥，而非主要的生产密钥。
• 提示词注入。 NorthData 响应包含用户生成的文本（公司描述、公告），攻击者可能会在其中塞入指令。应将工具输出视为不可信数据，而非可信的 LLM 指令。

---

开发

cd northdata-mcp
python -m venv .venv && source .venv/bin/activate
pip install -e "../northdata-cli"   # local editable CLI
pip install -e ".[dev]"
pytest

测试使用 FastMCP 的内存传输方式，无需子进程，也无需网络。底层的 NorthDataClient 通过基于 httpx.MockTransport 的模拟工厂注入。

---

资源

• 模型上下文协议： https://modelcontextprotocol.io
• FastMCP v3 文档： https://gofastmcp.com
• NorthData API： https://github.com/northdata/api
• 同系列软件包： northdata-cli — 相同的工具，采用纯命令行形式

---

许可证

MIT。请参阅 LICENSE。