mcp-openapi-proxy
mcp-openapi-proxyは、Model Context Protocol (MCP) サーバーを実装する Python パッケージです。OpenAPI 仕様で定義された REST API を MCP ツールとして動的に公開するように設計されています。これにより、OpenAPI で記述された API を MCP ベースのワークフローにシームレスに統合できます。
目次
概要
このパッケージには 2 つの動作モードがあります。
- 低レベルモード (デフォルト): OpenAPI ドキュメントで指定されたすべての有効な API エンドポイントに対応するツールを動的に登録します (例:
/chat/completions``chat_completions()
になります)。 - **FastMCP モード (シンプル モード):**静的構成に基づいて定義済みのツール セット (
list_functions()
やcall_function()
など) を公開することで、合理化されたアプローチを提供します。
特徴
- 動的ツール生成: OpenAPI エンドポイント定義から MCP ツールを自動的に作成します。
- シンプル モード オプション: FastMCP モードを介して静的構成の代替手段を提供します。
- OpenAPI 仕様のサポート: OpenAPI v3 と互換性があり、v2 もサポートされる可能性があります。
- **柔軟なフィルタリング:**パスやその他の基準によるホワイトリストによるエンドポイントのフィルタリングを可能にします。
- ペイロード認証: JMESPath 式によるカスタム認証をサポートします (例: HTTP ヘッダーではなくペイロード内のトークンを期待する Slack などの API の場合)。
- ヘッダー認証: Authorization ヘッダーの
API_KEY
にはデフォルトでBearer
を使用します。ApiApi-Key
を必要とする Fly.io などの API に合わせてカスタマイズ可能です。 - MCP 統合: REST API をツールとして呼び出すために MCP エコシステムとシームレスに統合します。
インストール
次のコマンドを使用して、PyPI からパッケージを直接インストールします。
MCPエコシステム統合
mcp-openapi-proxy をMCPエコシステムに組み込むには、 mcpServers
設定内で設定します。以下に一般的な例を示します。
特定の API に合わせた実際の構成については、以下の例のセクションを参照してください。
動作モード
FastMCPモード(シンプルモード)
- **有効化方法:**環境変数
OPENAPI_SIMPLE_MODE=true
を設定します。 - **説明:**コードで定義されている特定の OpenAPI エンドポイントから派生した固定のツール セットを公開します。
- **構成:**ツールの動作を指定するには環境変数に依存します。
低レベルモード(デフォルト)
- **説明:**提供された OpenAPI 仕様からすべての有効な API エンドポイントを個別のツールとして自動的に登録します。
- **ツールの命名:**正規化された OpenAPI パスとメソッドからツール名を派生します。
- 動作: OpenAPI 操作の概要と説明からツールの説明を生成します。
環境変数
OPENAPI_SPEC_URL
: (必須) OpenAPI 仕様 JSON ファイルへの URL (例:https://example.com/spec.json
またはfile:///path/to/local/spec.json
)。OPENAPI_LOGFILE_PATH
: (オプション) ログ ファイルのパスを指定します。OPENAPI_SIMPLE_MODE
: (オプション) FastMCP モードを有効にするにはtrue
に設定します。TOOL_WHITELIST
: (オプション) ツールとして公開するエンドポイント パスのコンマ区切りリスト。TOOL_NAME_PREFIX
: (オプション) すべてのツール名の先頭に付けるプレフィックス。API_KEY
: (オプション) デフォルトでは Authorization ヘッダーでBearer <API_KEY>
として送信される API の認証トークン。API_AUTH_TYPE
: (オプション) デフォルトのBearer
Authorization ヘッダー タイプ (GetZep の場合はApi-Key
など) をオーバーライドします。STRIP_PARAM
: (オプション) 不要なパラメータを削除するための JMESPath 式 (例: Slack のtoken
)。DEBUG
: (オプション) 「true」、「1」、または「yes」に設定すると、詳細なデバッグ ログが有効になります。EXTRA_HEADERS
: (オプション) 送信 API リクエストに添付する「ヘッダー: 値」形式の追加の HTTP ヘッダー (1 行に 1 つ)。SERVER_URL_OVERRIDE
: (オプション) 設定時に OpenAPI 仕様のベース URL をオーバーライドします。カスタム展開に役立ちます。TOOL_NAME_MAX_LENGTH
: (オプション) ツール名を最大長に切り捨てます。- 追加変数:
OPENAPI_SPEC_URL_<hash>
– テストごとに固有の構成のバリアント (OPENAPI_SPEC_URL
にフォールバックします)。 IGNORE_SSL_SPEC
: (オプション) OpenAPI 仕様を取得するときに SSL 証明書の検証を無効にするには、true
に設定します。IGNORE_SSL_TOOLS
: (オプション) ツールによって行われた API リクエストの SSL 証明書検証を無効にするには、true
に設定します。
例
テストとして、例に示されているようにuvxコマンドを実行し、JSON-RPCメッセージを介してMCPサーバーとやり取りしてツールとリソースを一覧表示することができます。以下の「JSON-RPCテスト」セクションをご覧ください。
Glamaの例
Glama は、 OPENAPI_SPEC_URL
環境変数のみを必要とする、mcp-openapi-proxy の最小限の設定を提供します。このシンプルさは、迅速なテストに最適です。
1. OpenAPI仕様を確認する
Glama OpenAPI 仕様を取得します。
応答が有効な OpenAPI JSON ドキュメントであることを確認します。
2. Glama用にmcp-openapi-proxyを設定する
MCP エコシステム設定に次の構成を追加します。
3. テスト
次のようにしてサービスを開始します。
次に、リソースとツールをリストする手順については、 JSON-RPC テストのセクションを参照してください。
Fly.ioの例
Fly.ioはマシン管理用のシンプルなAPIを提供しており、理想的な出発点となります。Fly.ioのドキュメントからAPIトークンを取得してください。
1. OpenAPI仕様を確認する
Fly.io OpenAPI 仕様を取得します。
応答が有効な OpenAPI JSON ドキュメントであることを確認します。
2. Fly.io 用に mcp-openapi-proxy を設定する
MCP エコシステム構成を更新します。
- OPENAPI_SPEC_URL : Fly.io OpenAPI 仕様を指します。
- API_KEY : Fly.io API トークン (
<your_flyio_token_here>
を置き換えます)。 - API_AUTH_TYPE : Fly.io のヘッダーベースの認証の
Api-Key
に設定します (デフォルトのBearer
を上書きします)。
3. テスト
サービスを開始した後、リソースとツールの一覧表示の手順については、JSON-RPC テストのセクションを参照してください。
レンダリング例
Renderは、API経由で管理可能なインフラストラクチャホスティングを提供しています。提供されている設定ファイルexamples/render-claude_desktop_config.json
は、最小限の設定でMCPエコシステムを迅速にセットアップする方法を示しています。
1. OpenAPI仕様を確認する
Render OpenAPI 仕様を取得します。
応答が有効な OpenAPI ドキュメントであることを確認します。
2. レンダリング用にmcp-openapi-proxyを設定する
MCP エコシステム設定に次の構成を追加します。
3. テスト
レンダリング設定を使用してプロキシを起動します。
次に、リソースとツールをリストする手順については、 JSON-RPC テストのセクションを参照してください。
Slackの例
Slack APIでは、JMESPathを使用して不要なトークンペイロードを削除する方法を紹介します。ボットトークンはSlack APIドキュメントから取得してください。
1. OpenAPI仕様を確認する
Slack OpenAPI 仕様を取得します。
有効な OpenAPI JSON ドキュメントであることを確認してください。
2. Slack 用に mcp-openapi-proxy を設定する
設定を更新します:
- OPENAPI_SPEC_URL : Slack の OpenAPI 仕様 URL。
- TOOL_WHITELIST : ツールを有用なエンドポイント グループ (チャット、会話、ユーザーなど) に制限します。
- API_KEY : Slack ボット トークン (例:
xoxb-...
、<your_slack_bot_token>
を置き換えます)。 - STRIP_PARAM : リクエストペイロードからトークンフィールドを削除します。
- TOOL_NAME_PREFIX : ツール名の先頭に
slack_
を追加します。
3. テスト
サービスを開始した後、リソースとツールの一覧表示の手順については、JSON-RPC テストのセクションを参照してください。
GetZepの例
GetZepは、詳細なエンドポイントを備えたメモリ管理用の無料クラウドAPIを提供しています。GetZepは公式のOpenAPI仕様を提供していないため、このプロジェクトでは利便性のためにGitHubでホストされた生成された仕様が含まれています。ユーザーは同様に、任意のREST APIのOpenAPI仕様を生成し、ローカルで参照することができます(例: file:///path/to/spec.json
)。APIキーはGetZepのドキュメントから取得してください。
1. OpenAPI仕様を確認する
プロジェクト提供の GetZep OpenAPI 仕様を取得します。
有効なOpenAPI JSONドキュメントであることを確認してください。または、独自の仕様を生成し、 file://
URLを使用してローカルファイルを参照することもできます。
2. GetZep 用に mcp-openapi-proxy を設定する
設定を更新します:
- OPENAPI_SPEC_URL : プロジェクト提供の GetZep Swagger 仕様を指します (または、ローカル ファイルの場合は
file:///path/to/your/spec.json
を使用します)。 - TOOL_WHITELIST :
/sessions
エンドポイントへの制限。 - API_KEY : GetZep API キー。
- API_AUTH_TYPE : ヘッダーベースの認証に
Api-Key
使用します。 - TOOL_NAME_PREFIX : ツール名の先頭に
zep_
を追加します。
3. テスト
サービスを開始した後、リソースとツールの一覧表示の手順については、JSON-RPC テストのセクションを参照してください。
Virustotalの例
この例では次のことを示します。
- YAML OpenAPI仕様ファイルの使用
- カスタム HTTP 認証ヘッダー「x-apikey」を使用する
1. OpenAPI仕様を確認する
Virustotal OpenAPI 仕様を取得します。
応答が有効な OpenAPI YAML ドキュメントであることを確認します。
2. Virustotal用にmcp-openapi-proxyを設定する
MCP エコシステム設定に次の構成を追加します。
主な構成ポイント:
- デフォルトでは、プロキシは JSON 仕様を想定し、Bearer プレフィックス付きの API キーを送信します。
- YAML OpenAPI 仕様を使用するには、
OPENAPI_SPEC_FORMAT="yaml"
を含めます。 - 注意: VirusTotal には特別な認証ヘッダーが必要です。EXTRA_HEADERS は API キーを「x-apikey: ${VIRUSTOTAL_API_KEY}」として送信するために使用されます。
3. テスト
Virustotal 設定でプロキシを起動します。
サービスを開始した後、リソースとツールの一覧表示の手順については、JSON-RPC テストのセクションを参照してください。
概念の例
NotionのAPIでは、HTTPヘッダーで特定のバージョンを指定する必要があります。この例では、 EXTRA_HEADERS
環境変数を使用して必要なヘッダーを追加し、OpenAPI仕様の検証に重点を置いています。
1. OpenAPI仕様を確認する
Notion OpenAPI 仕様を取得します。
応答が有効な YAML ドキュメントであることを確認します。
2. Notion用にmcp-openapi-proxyを設定する
MCP エコシステム設定に次の構成を追加します。
3. テスト
Notion 構成でプロキシを起動します。
サービスを開始した後、リソースとツールの一覧表示の手順については、JSON-RPC テストのセクションを参照してください。
アーサナの例
Asana は、ワークスペース、タスク、プロジェクト、ユーザーを管理するための豊富なエンドポイントを提供しています。統合テストではGET /workspaces
、 GET /tasks
、 GET /projects
などのエンドポイントの使用方法を示します。
1. OpenAPI仕様を確認する
Asana OpenAPI 仕様を取得します。
応答が有効な YAML (または JSON) ドキュメントであることを確認します。
2. Asana 用に mcp-openapi-proxy を設定する
MCP エコシステム設定に次の構成を追加します。
注: ほとんどの Asana API エンドポイントは認証が必要です。有効なトークンを使用して、環境または.env
ファイルでASANA_API_KEY
設定してください。
3. テスト
次のようにしてサービスを開始します。
その後、MCP エコシステムを使用して、 /dcim/devices/
や/ipam/ip-addresses/
などのエンドポイントのツールを一覧表示したり、呼び出すことができます。
APIs.guruの例
APIs.guru は、数千もの公開 API の OpenAPI 定義ディレクトリを提供します。この例では、mcp-openapi-proxy を使用して APIs.guru ディレクトリを MCP ツールとして公開する方法を示します。
1. OpenAPI仕様を確認する
APIs.guru OpenAPI 仕様を取得します。
応答が有効な OpenAPI YAML ドキュメントであることを確認します。
2. APIs.guru 用に mcp-openapi-proxy を設定する
MCP エコシステム設定に次の構成を追加します。
3. テスト
次のようにしてサービスを開始します。
その後、MCP エコシステムを使用して、APIs.guru ディレクトリで定義されているlistAPIs
、 getMetrics
、 getProviders
などのツールを一覧表示して呼び出すことができます。
ネットボックスの例
NetBoxは、オープンソースのIPアドレス管理(IPAM)およびデータセンターインフラストラクチャ管理(DCIM)ツールです。この例では、mcp-openapi-proxyを使用してNetBox APIをMCPツールとして公開する方法を示します。
1. OpenAPI仕様を確認する
NetBox OpenAPI 仕様を取得します。
応答が有効な OpenAPI YAML ドキュメントであることを確認します。
2. NetBox用にmcp-openapi-proxyを設定する
MCP エコシステム設定に次の構成を追加します。
注: ほとんどのNetBox APIエンドポイントは認証が必要です。環境または.env
ファイルでNETBOX_API_KEY
有効なトークンを設定してください。
3. テスト
次のようにしてサービスを開始します。
その後、MCP エコシステムを使用して、 /dcim/devices/
や/ipam/ip-addresses/
などのエンドポイントのツールを一覧表示したり、呼び出すことができます。
Box APIの例
Boxアカウントへの認証アクセスには、独自の開発者トークンを使用してBox Platform APIを統合できます。この例では、Box APIエンドポイントをMCPツールとして公開する方法を示します。
設定例: examples/box-claude_desktop_config.json
- Box開発者トークンを
.env
の環境変数として設定します。 - または、次の 1 行でプロキシを実行します。
MCPエコシステムを使用してBox APIツールの一覧を表示および呼び出しできるようになりました。統合テストについては、 tests/integration/test_box_integration.py
をご覧ください。
注意: 無料レベルのボックス ユーザーの開発者 API キーは 60 分に制限されています :(。
WolframAlpha APIの例
認証アクセスのために、独自のApp IDを使用してWolframAlpha APIを統合できます。この例では、WolframAlpha APIエンドポイントをMCPツールとして公開する方法を示します。
設定例: examples/wolframalpha-claude_desktop_config.json
- WolframAlpha アプリ ID を
.env
の環境変数として設定します。 - または、次の 1 行でプロキシを実行します。
MCPエコシステムを使用して、WolframAlpha APIツールの一覧を表示および呼び出しできるようになりました。統合テストについては、 tests/integration/test_wolframalpha_integration.py
をご覧ください。
トラブルシューティング
JSON-RPC テスト
代替テストとして、JSON-RPC経由でMCPサーバーとやり取りすることもできます。サーバーを起動したら、以下の初期化メッセージを貼り付けてください。
予想される応答:
次に、次のフォローアップメッセージを貼り付けます。
- **OPENAPI_SPEC_URL がありません:**有効な OpenAPI JSON URL またはローカル ファイル パスに設定されていることを確認してください。
- 無効な仕様: OpenAPI ドキュメントが標準に準拠していることを確認してください。
- ツール フィルタリングの問題:
TOOL_WHITELIST
目的のエンドポイントと一致しているかどうかを確認します。 - 認証エラー:
API_KEY
とAPI_AUTH_TYPE
が正しいことを確認してください。 - ログ: stderr に詳細を出力するには、
DEBUG=true
を設定します。 - **テストサーバー:**直接実行:
ライセンス
This server cannot be installed
remote-capable server
The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.
OpenAPI で記述された REST API を MCP ワークフローに統合し、API エンドポイントを MCP ツールとして動的に公開できるようにする Python ベースの MCP サーバー。
Related Resources
Related MCP Servers
- -securityFlicense-qualityThis is an MCP server that facilitates building tools for interacting with various APIs and workflows, supporting Python-based development with potential for customizable prompts and user configurations.Last updated -Python
- AsecurityFlicenseAqualityAn MCP server implementation that enables interaction with the Unstructured API, providing tools to list, create, update, and manage sources, destinations, and workflows.Last updated -3928
- -securityFlicense-qualityA Python-based MCP server that dynamically fetches plugin definitions from SuperiorAPIs and auto-generates tool functions based on OpenAPI schemas, enabling seamless integration with API services.Last updated -Python
- -securityAlicense-qualityGenerate an MCP server for any OpenAPI documented endpoint.Last updated -201GoApache 2.0
Appeared in Searches
- How to handle REST APIs
- Making API documentation usable for LLMs
- Troubleshooting 'fetch 中stdio启用失败' Error
- Developing AI-Powered Mobile and Web Applications by Combining and Transferring Knowledge from Open Source AI Models
- A team of expert data scientists with Python, Pandas, and SQL skills for implementation guidance