MCP API Translator

mcp-api-translator

一个用于生成 MCP 服务的 MCP 服务。 提供 API 定义——OpenAPI 3.0/3.1 或 Postman 集合——即可为该 API 搭建一个完整、可运行、由你掌控 的 TypeScript 或 Python MCP 服务。

上图：将 Firecrawl 的 20 个操作精简到 6 个，将 Gmail API 添加到同一个服务中，然后由 Agent 调用可自托管的结果。计数、工具名称和路径来自针对已发布的 Firecrawl 和 Gmail 描述的实际运行；API 响应仅作示例——录制过程使用本地存根，而非在线 Firecrawl 或 Gmail 账号。

为什么不采用一对一生成器

将 OpenAPI 规范转换为 MCP“工具存根”并不新鲜——FastMCP 的 from_openapi、Speakeasy/Gram 以及多个 openapi-mcp-generator 项目早已实现了机械化转换。简单的端点→工具生成器并无真正优势。本项目专注于这些工具所忽略的部分：

1. 筛选，而不只是生成。 一个有 200 个端点的 API，简单生成就会变成 200 个工具，这会严重损害模型选择工具的准确性，并耗尽上下文。analyze_spec 会在写入任何内容前预览工具列表；每条命令都支持 includeTags / methods / pathGlob / excludeOperations，当服务的工具数量超过 40 个时还会发出警告。

2. 通过追加来聚合。 extend_mcp_server 会将另一个 API 的工具添加到现有项目中，因此你可以构建一个横跨 Firecrawl、Gmail 和内部 API 的 MCP 服务。凭据彼此独立：每个 API 也会读取根据其标题生成的命名空间环境变量。

3. 由你拥有的产物。 输出是一个普通项目，而不是托管的黑盒——包含易于阅读的逐工具文件、基于环境变量的身份验证、Dockerfile、server.json，以及用于发布到官方 MCP 注册表的客户端代码片段。

如果你只需要临时在内存中暴露一个 API，并不关心是否拥有代码，那么 FastMCP 的运行时模式可能更适合你——这是本项目有意不支持的目标。

安装

无需安装步骤。npx 会获取并运行最新发布版本——跨平台，要求 Node 20+。

Claude Code

Claude Code 不会读取 claude_desktop_config.json——它使用自己的 MCP 配置：

claude mcp add api-translator -- npx -y mcp-api-translator

这会将其注册到 local 作用域。使用 -s user 可应用于所有项目，或提交项目作用域的 .mcp.json 以便共享。使用 claude mcp list 验证。

Claude Desktop

添加到 claude_desktop_config.json（macOS： ~/Library/Application Support/Claude/claude_desktop_config.json，Windows： %APPDATA%\Claude\claude_desktop_config.json）：

{
  "mcpServers": {
    "api-translator": {
      "command": "npx",
      "args": ["-y", "mcp-api-translator"]
    }
  }
}

{
  "mcpServers": {
    "api-translator": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "ghcr.io/krishgok/mcp-api-translator:latest"]
    }
  }
}

MCP 配置会在启动时读取，因此请重启客户端——退出并重新打开 Claude Desktop、Cursor 等， 或在 Claude Code 中启动新会话。

四种工具

所有规范输入都支持内联文本（spec）或本地路径（specPath），格式可为 JSON 或 YAML。

用法

你无需手动调用这些工具，只需向 Agent 提出要求，由它来驱动这些工具。

1. 预览，然后筛选。 在写入任何内容前，查看规范会生成什么：

“分析 ./petstore.yaml，并展示建议生成的工具。” “只要 /pets 下的 GET 端点。”

analyze_spec({ specPath: "./petstore.yaml" });
// → proposed tool list, auth scheme, and the env vars the server will need

analyze_spec({ specPath: "./petstore.yaml", methods: ["GET"], pathGlob: "/pets/**" });
// also: includeTags: ["pets"], excludeOperations: ["deletePet"]

2. 生成，使用相同的筛选条件，并指定输出目录：

generate_mcp_server({ specPath: "./petstore.yaml", outputDir: "./petstore-mcp" });
// options: language: "python", transport: "http", auth: {...}, force: true

3. 聚合——向同一服务添加更多 API：

// any second API — the sources don't have to share a format or a vendor
extend_mcp_server({
  projectDir: "./petstore-mcp",
  specPath: "./billing.postman.json",
  includeTags: ["invoices"],
});
// idempotent; hand-edited tool files are preserved

聚合的 API 不共用凭据：每个 API 还会先读取带命名空间的环境变量 （<NAMESPACE>_API_BASE_URL、<NAMESPACE>_API_KEY 等，命名空间根据 API 标题生成）， 然后才回退到不带命名空间的变量。扩展摘要和 .env.example 会列出确切的变量名。

4. 运行。 输出是一个归你所有的常规项目：

cd petstore-mcp && npm install && npm run build
cp .env.example .env   # set API_BASE_URL + credentials (never embedded in code)
npm start

使用生成的 client-config.md 将其注册到客户端，然后你的 Agent 就能直接调用这些 API。

包含示例输出和故障排除的完整演练： docs/usage-workflow.md。

生成，或服务

• 生成可由你掌控的代码：如果你想要一个可以手动编辑、可自托管并归你所有的项目，可使用 TypeScript（默认）或 Python（language: "python"）。

• 服务实时运行时代理：如果你只想立即向 Agent 暴露 API，而不想构建或维护生成的文件：

  mcp-api-translator serve --spec ./api.yaml
  mcp-api-translator serve --spec ./a.yaml --spec ./b.yaml --methods GET,POST   # aggregate
  

serve 运行与生成器输出相同的请求计划和基于环境变量的身份验证，因此行为与生成的输出完全一致——只是跳过了代码生成步骤。它默认使用 stdio，也支持无状态的 Streamable HTTP（使用 --transport http --port 3000）。容器中会在 stderr 输出结构化 JSON 行日志，在 TTY 中则输出易读文本（LOG_LEVEL、LOG_FORMAT）。

文档

已知限制一览：

• 输入： OpenAPI 3.0/3.1 和 Postman v2.1（尽力支持 Swagger 2.0）。不支持 GraphQL 和 gRPC。
• 身份验证： 对于支持的 OpenAPI/Postman API，目前尚无交互式 OAuth 授权流程； 计划在 R6 中实现。
• 响应： 不支持上游流式传输或自动分页。
• 输出质量取决于规范质量。

详情和安全模型请参阅：docs/design.md。

开发

npm install
npm test          # unit + integration (parsers, curation, emit, append)
npm run typecheck
npm run build
npm run e2e       # generate a sample project from the fixtures into build/e2e-out

欢迎贡献——请参阅 CONTRIBUTING.md。所有提交都必须按照 Developer Certificate of Origin 的要求进行签署（git commit -s）。

许可证

mcp-api-translator 采用双重许可——© 2026 krishgok。完整详情请参阅 LICENSING.md。

• 开源： GNU AGPL-3.0-or-later。将修改后的版本作为网络服务运行，必须向用户提供该版本的完整源代码。
• 商业用途： 可单独获取许可证，以便在专有产品中嵌入而不受 AGPL 义务约束。
• 生成的输出归你所有。 此工具生成的项目受生成输出例外条款保护，不受 AGPL 约束。

重新分发时必须保留 LICENSE 和 NOTICE。未经事先书面许可，这些许可证不 授予使用 “mcp-api-translator” 名称为分叉或衍生作品背书或推广的权利。