MCP API Translator

mcp-api-translator

MCP サーバーを生成する MCP サーバーです。 API 定義（OpenAPI 3.0/3.1 または Postman コレクション）を渡すと、その API 用の完全に動作し、自分で所有できる TypeScript または Python の MCP サーバーをひな形から生成します。

上図：Firecrawl の 20 個の操作を 6 個に整理し、同じサーバーに Gmail API を追加してから、エージェントがセルフホストした結果を呼び出しています。件数、ツール名、パスは、公開されている Firecrawl と Gmail の説明を使った実際の実行結果です。API のレスポンスは説明用であり、録画は実際の Firecrawl アカウントや Gmail アカウントではなく、ローカルのスタブに対して実行しています。

1対1のジェネレーターではなく、これを使う理由

OpenAPI 仕様を MCP の「ツールのスタブ」に変換すること自体は、新しいものではありません。FastMCP の from_openapi、Speakeasy/Gram、およびいくつかの openapi-mcp-generator プロジェクトが、すでに機械的な処理を行っています。単純なエンドポイントからツールへのジェネレーターに、実質的な優位性はありません。このプロジェクトは、そうしたツールが対応しない部分に重点を置いています。

1. 生成だけでなく、整理。 200 個のエンドポイントをそのまま変換すると、200 個のツールになり、モデルのツール選択精度を損ない、コンテキストを圧迫します。analyze_spec は書き込み前にツール一覧をプレビューします。すべてのコマンドで includeTags / methods / pathGlob / excludeOperations を指定でき、サーバーのツール数が 40 個を超えると警告が表示されます。

2. 追加による集約。 extend_mcp_server は別の API のツールを既存のプロジェクトに追加するため、Firecrawl、Gmail、自社の内部 API にまたがる 1つの MCP サーバーを構築できます。認証情報は個別に管理されます。各 API は、タイトルから生成された名前空間付き環境変数も読み込みます。

3. 自分で所有できる成果物。 出力されるのはホスト型のブラックボックスではなく、通常のプロジェクトです。ツールごとに読みやすいファイル、環境変数ベースの認証、Dockerfile、さらに 公式 MCP Registry への公開に使える server.json とクライアント用スニペットが含まれます。

コードを所有する必要がなく、1つの 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 で新しいセッションを開始します。

4 つのツール

すべての仕様入力は、インラインテキスト（spec）またはローカルパス（specPath）に対応し、JSON または YAML を使用できます。

使用方法

ツールを手動で呼び出す必要はありません。エージェントに依頼すれば、エージェントがツールを操作します。

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 を使ってクライアントに登録すれば、エージェントが API を直接呼び出せるようになります。

サンプル出力とトラブルシューティングを含む詳しい手順： docs/usage-workflow.md。

生成するか、サーブするか

• 生成 — 手編集、セルフホスト、自分での管理が可能なプロジェクトが必要な場合は、所有できるコードを生成します。TypeScript（デフォルト）または Python（language: "python"）に対応しています。

• サーブ — 生成ファイルのビルドや保守をせずに、API を今すぐエージェントに公開したい場合は、ライブランタイムプロキシを実行します。

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

serve は、ジェネレーターが出力するものと同じリクエストプランおよび環境変数ベースの認証を使用するため、動作は生成された出力と完全に一致します。コード生成の手順を省略するだけです。デフォルトでは stdio を使用します。また、--transport http --port 3000 を指定すると、ステートレスな Streamable HTTP を使用します。コンテナでは 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」の名称を使用する権利を 付与しません。