getapi

GetApi MCP Server

一款 MCP 服务，可将 GetApi API 提供给 Claude Desktop 等 AI 客户端使用。

安装

通过 npm 安装服务：

npm install -g getapi-mcp

功能

此服务将所有 GetApi API 端点提供为 AI 客户端可用的工具。服务通过 stdio 通信，并使用 npx getapi-mcp 启动。API 密钥仅通过环境变量 API_KEY 设置。

要求

• Node.js 20 LTS 或更高版本
• 有效的 GetApi API 密钥

配置

CLI 用法

npx getapi-mcp

MCP 服务配置

将以下配置添加到客户端的 MCP 配置中（例如 Claude Desktop 的 claude_desktop_config.json）：

{
  "mcpServers": {
    "getapi": {
      "command": "npx",
      "args": ["-y", "[email protected]"],
      "env": {
        "API_KEY": "ga_live_xxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

重要：API 密钥只能通过 env 设置。服务会在日志和输出中完全屏蔽密钥。

获取 API 密钥

你需要拥有一个有效的 GetApi API 密钥。有关创建和管理密钥的信息，请参阅其控制面板。

注意：密钥格式必须为 ga_live_xxxxx 或 ga_test_xxxxx。

可用工具

工具列表由 GetApi OpenAPI 规范自动生成，并每小时更新一次。

工具示例

工具	描述
getapi_kadaster_bag_address	按邮政编码和门牌号搜索地址（BAG）
getapi_kadaster_bag_address-suggest	地址自动补全建议
getapi_kadaster_bag_id	按地址标识符 ID 搜索地址
getapi_lookup_postcode	邮政编码查询（NL）
getapi_lookup_ip	IP/ISP 信息
getapi_validation_iban	验证 IBAN / BIC
getapi_validation_vat	验证欧盟增值税号（VIES）
getapi_property_pandgegevens	按邮政编码和门牌号查询建筑信息
getapi_rdw_vehicle	按车牌号查询车辆信息（RDW）
getapi_lookup_dns_records	查询域名的 DNS 记录
...	完整列表由 OpenAPI 规范生成

查看 GetApi API 文档以获取完整的端点列表。

用法

调用工具

1. 点击 MCP 图标（通常位于聊天界面中）
2. 将 GetApi 服务添加为 MCP 服务
3. 在 MCP 面板中点击某个工具
4. 填写必需参数
5. 工具将执行并显示结果

错误代码

发生网络错误时，你会收到具体的错误消息：

代码	描述	解决方案
404	未找到资源	检查 URL 和参数
400	参数错误	检查参数语法
422	验证错误	检查参数类型
503	服务暂时不可用	请稍后重试
TIMEOUT	请求超时	增加超时时间
401	API 密钥无效	检查 API 密钥

安全性

• API 密钥绝不会出现在日志、输出或工具结果中
• 所有请求仅发送到 https://api.getapi.nl
• 服务会自动屏蔽日志中的 API 密钥
• 密钥绝不会发送给 GetApi

自动更新

服务每小时检查一次 GetApi 规范是否发生变化。更新时：

• 工具列表会自动更新
• 客户端会收到通知（取决于客户端支持情况）
• 无效规范将被忽略，并回退到最近一次的有效版本

注意：并非所有 MCP 客户端都能处理自动更新。如果要查看新工具，请重启客户端。

已知限制

1. x402 端点：不提供需付费的 AI 端点（AI 客户端无需使用）
2. 客户端支持：工具列表发生变化时，请重启客户端
3. 超时：请求超时时间为 10 秒
4. 响应大小：响应最大为 1 MB
5. 规范大小：OpenAPI 规范最大为 5 MB

配置选项

这些值目前在服务端固定设置（无法通过 env 修改）；只有 API_KEY 是环境变量。

选项	默认值	描述
specUrl	https://api.getapi.nl/docs/api.json	GetApi OpenAPI 规范的 URL
baseUrl	https://api.getapi.nl	API 请求的基础 URL
authHeader	X-Api-Key	身份验证的标头名称
refreshIntervalMs	3600000（1 小时）	检查规范的间隔
timeoutMs	10000	请求超时时间（毫秒）
maxResponseSize	1048576	最大响应大小（1 MB）
maxSpecSize	5242880	最大规范大小（5 MB）
x402ExcludedOperations	空	不作为工具导出的操作 ID

配置示例

唯一的环境变量是 API_KEY：

{
  "mcpServers": {
    "getapi": {
      "command": "npx",
      "args": ["-y", "[email protected]"],
      "env": {
        "API_KEY": "ga_live_xxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

故障排除

“未设置或无效的 API_KEY”

如果缺少 API_KEY，或者它不以 ga_live_/ga_test_ 开头，服务会显示此消息并停止。请通过 MCP 客户端配置设置该变量（参见“配置”）。

“没有可用的规范”

• 无法访问规范 URL（https://api.getapi.nl/docs/api.json）
• GetApi 规范暂时不可用
• 检查你的互联网连接

此时服务会仅使用 getapi_ping 后备工具启动，并在下次刷新时重试。

“参数验证失败”

• 根据工具的 inputSchema 检查参数名称和类型
• 必填参数列在 required 中

状态码错误（例如 401/404）

• 401：API 密钥无效或缺失
• 404：参数错误或端点未知
• 503/504：API 暂时不可用或请求超时

开发与测试

# Afhankelijkheden installeren
npm install

# Alles valideren: typecheck + lint + build + tests (unit + e2e)
npm run validate

# Volledige check inclusief smoke-test van het gepackagede npm-artefact
npm run verify

# Alleen de tests
npm test

# Tests met coverage (en coverage-thresholds)
npm run test:coverage

# Documentatiecheck: links, ankers, versies en config-waarden
npm run check:docs

# Live contract test tegen de echte API (vereist API_KEY)
API_KEY=ga_test_... npm run test:live

# Smoke-test: pakt + installeert + start het echte pakket
npm run test:package

# Typecheck / lint afzonderlijk
npm run typecheck
npm run lint

# Bouwen naar dist/
npm run build

CI 会在每次推送/PR 时自动运行这些检查：.github/workflows/ci.yml；发布前则运行 .github/workflows/release.yml。

在本地运行服务

服务通过 stdio 与 MCP 客户端通信。若要快速手动检查，可以直接启动服务，并通过 stdin 向其发送 JSON-RPC 消息：

# Start de server (met een geldige ga_live_/ga_test_ key)
API_KEY="ga_test_1234567890" node dist/bin.js

然后向 stdin 发送如下内容：

{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"cli","version":"1.0.0"}}}

所有日志行都会显示在 stderr 中；stdout 仅包含 JSON-RPC。这样可以直接确认服务是否正确启动，以及有哪些工具可用。

在 MCP 客户端中运行

使用 MCP 服务配置 中的配置。客户端会通过 stdio（command: "npx"）自行启动服务，并通过 env 传入 API 密钥；无需端口或 URL。

版本

更新和改进列表请参见 CHANGELOG。

许可证

MIT License——详情请参见 LICENSE。

支持

如有问题、Bug 或建议，请通过以下方式联系：

• Email：[email protected]
• GitHub Issues：https://github.com/GetApiNL/mcp-server/issues

---

注意：此服务仅适用于有效的 GetApi API 密钥。没有有效的 API 密钥，服务将无法运行。