Grpc Invoke Mcp

gRPC Invoke MCP

grpc-invoke-mcp は、Claude Code、Codex、Cursor などの MCP 互換ツールから gRPC メソッドを呼び出すための MCP サーバーです。

エージェントが、サーバーリフレクションまたはローカルの .proto ファイルを使って、gRPC API を簡単に調査し、単項 RPC を呼び出せるようにします。エージェントがサービスを探索し、リクエストとレスポンスのスキーマを把握し、実際に gRPC を呼び出し、エージェント主導の開発中に使い捨てのスクリプトを書かずに gRPC 連携をテストしたい場合に便利です。

機能

• MCP 互換エージェントから gRPC メソッドを呼び出す
• gRPC サービス、メソッド、メッセージ型を記述する
• サーバーリフレクションまたはローカルの .proto ファイルを使う
• TLS またはプレーンテキストの HTTP/2 経由で接続する
• カスタムメタデータヘッダーを送信する
• 単項 RPC に JSON リクエストボディを渡す
• Claude Code、Codex、Cursor などの MCP クライアントで動作する

インストール

npx でサーバーを実行します。

npx -y @grulex/grpc-invoke-mcp@latest

インストール時に、パッケージがプラットフォーム固有の grpc-invoke-mcp バイナリをダウンロードします。

エージェントの設定

Claude Code

プロジェクトの設定ファイル：.mcp.json

{
  "mcpServers": {
    "grpc-invoke": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@grulex/grpc-invoke-mcp@latest"]
    }
  }
}

CLI での設定（任意）：

claude mcp add --transport stdio grpc-invoke -- npx -y @grulex/grpc-invoke-mcp@latest

Codex

ユーザーの設定ファイル：~/.codex/config.toml

[mcp_servers.grpc-invoke]
command = "npx"
args = ["-y", "@grulex/grpc-invoke-mcp@latest"]

CLI での設定（任意）：

codex mcp add grpc-invoke -- npx -y @grulex/grpc-invoke-mcp@latest

Cursor

プロジェクトの設定ファイル：.cursor/mcp.json

{
  "mcpServers": {
    "grpc-invoke": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@grulex/grpc-invoke-mcp@latest"]
    }
  }
}

~/.cursor/mcp.json にグローバルインストールすることもできます。

利用可能なツール

grpc_describe

このツールを使って、サービス、メソッド、メッセージ型を調査します。

主な用途：

• gRPC サーバーが公開しているサービスを一覧表示する
• 呼び出す前にメソッドのシグネチャを確認する
• リフレクションを使ってメッセージスキーマを調べる
• ローカルの .proto ファイルから API を記述する

grpc_call

このツールを使って、JSON リクエストボディで単項 gRPC メソッドを呼び出します。

主な用途：

• エージェントから内部マイクロサービスを呼び出す
• リクエストとレスポンスのペイロードをテストする
• 認証ヘッダーやその他の gRPC メタデータを送信する
• ローカル、ステージング、本番環境で安全なエンドポイントに接続する

プロンプトの例

• 「リフレクションを使って、localhost:50051 が公開しているサービスを説明してください。」
• 「helloworld.Greeter/SayHello のリクエストスキーマを表示してください。」
• 「{ \"name\": \"World\" } を指定して、localhost:50051 の helloworld.Greeter/SayHello を呼び出してください。」
• 「リフレクションの代わりに proto_files と import_paths を使って、package.Service/Method を呼び出してください。」

仕組み

このパッケージは、stdio 経由で MCP サーバーを公開します。エージェントがローカルでサーバーを起動し、次のようなツールを検出します。

• スキーマの調査に使う grpc_describe
• 単項 RPC の呼び出しに使う grpc_call

内部では、npm パッケージがインストール時に同梱されたネイティブの grpc-invoke-mcp バイナリを起動します。このバイナリは次に対応しています。

• gRPC サーバーリフレクション
• ローカルの .proto 定義
• プレーンテキストまたは TLS 接続
• リクエストのメタデータヘッダー

対応プラットフォーム

インストーラーは現在、次のプラットフォームを対象としています。

• macOS Apple Silicon
• macOS Intel
• Linux x64
• Linux ARM64
• Windows x64
• Windows ARM64

トラブルシューティング

npx でサーバーを起動できない

Node.js と npx がインストールされ、PATH から利用できることを確認してください。

バイナリのダウンロードに失敗する

npm パッケージはインストール時にリリース成果物をダウンロードするため、マシンが GitHub Releases にアクセスできる必要があります。

リフレクションが動作しない

接続先サーバーが gRPC リフレクションを公開していない場合は、代わりにローカルの .proto ファイルと import_paths を使ってください。

TLS または接続のエラー

接続先のホスト、ポート、TLS 設定、およびサーバーがプレーンテキストと TLS のどちらを想定しているかを確認してください。

エージェントが MCP サーバーを使用しない

クライアントに適した場所に設定ファイルがあることを確認してください。必要に応じてクライアントを再起動し、MCP 一覧またはツールパネルにサーバーが表示されていることを確認してください。

grpc-invoke-mcp を使用する理由

gRPC サービスを扱う場合、この MCP サーバーを使うと、AI エージェントがそれらのサービスを直接調査して呼び出せます。API の詳細を手作業で翻訳する代わりに、Claude Code、Codex、Cursor などの MCP 対応エージェントにコントラクトを調査させ、安全で的を絞ったリクエストを実行させることで、エージェント主導の開発ワークフローにおけるデバッグ、統合作業、API の調査、gRPC のテストを行えます。

ライセンス

MIT