MCP ジェミニサーバー

概要

このプロジェクトは@google/genai SDKをラップする専用のMCP（Model Context Protocol）サーバーを提供します。Google Geminiのモデル機能を標準のMCPツールとして公開することで、他のLLM（Clineなど）やMCP互換システムがGeminiの機能をバックエンドの主力として活用できるようになります。

このサーバーは、MCP 標準を介して管理される一貫性のあるツールベースのインターフェースを提供することにより、Gemini モデルとの統合を簡素化することを目的としています。

特徴

**コア生成:**標準 ( gemini_generateContent ) およびストリーミング ( gemini_generateContentStream ) テキスト生成。
関数呼び出し: Gemini モデルがクライアント定義関数 ( gemini_functionCall ) の実行を要求できるようにします。
**ステートフルチャット:**複数のターンにわたる会話のコンテキストを管理します ( gemini_startChat 、 gemini_sendMessage 、 gemini_sendFunctionResult )。
ファイル処理: Gemini API を使用してファイルをアップロード、一覧表示、取得、削除します。
**キャッシュ:**プロンプトを最適化するために、キャッシュされたコンテンツを作成、一覧表示、取得、更新、および削除します。

前提条件

Node.js (v18以降)
Google AI Studioからの API キー ( https://aistudio.google.com/app/apikey )。
- 重要:ファイル処理およびキャッシュAPIはGoogle AI Studio APIキーとのみ互換性があり、Vertex AI認証情報を使用する場合はサポートされません。このサーバーは現在、Vertex AI認証をサポートしていません。

インストールとセットアップ

Smithery経由でインストール

Smithery経由で Claude Desktop 用の Gemini Server を自動的にインストールするには:

npx -y @smithery/cli install @bsmi021/mcp-gemini-server --client claude

手動でインストールする

**プロジェクトの複製/配置:**システム上でmcp-gemini-serverプロジェクトディレクトリにアクセスできることを確認します。
**依存関係のインストール:**ターミナルでプロジェクトディレクトリに移動し、次のコマンドを実行します。
npm install
プロジェクトのビルド: TypeScript ソースコードをコンパイルします。
npm run build
このコマンドはTypeScriptコンパイラ（ tsc ）を使用し、JavaScriptファイルを./distディレクトリ（ tsconfig.jsonのoutDirで指定）に出力します。サーバーのメインエントリポイントはdist/server.jsになります。
MCPクライアントの設定： MCPクライアントの設定ファイル（例：Cline/VSCodeの場合はcline_mcp_settings.json 、Claudeデスクトップアプリの場合はclaude_desktop_config.json ）にサーバー設定を追加します。/path/to/mcp-gemini-server /path/to/mcp-gemini-serverシステム上の実際のパスに、 YOUR_API_KEYをGoogle AI Studioのキーに置き換えてください。
{ "mcpServers": { "gemini-server": { // Or your preferred name "command": "node", "args": ["/path/to/mcp-gemini-server/dist/server.js"], // Path to the compiled server entry point "env": { "GOOGLE_GEMINI_API_KEY": "YOUR_API_KEY", "GOOGLE_GEMINI_MODEL": "gemini-1.5-flash" // Optional: Set a default model }, "disabled": false, "autoApprove": [] } // ... other servers } }
MCPクライアントの再起動： MCPクライアントアプリケーション（例：Cline拡張機能付きのVS Code、Claudeデスクトップアプリ）を再起動して、新しいサーバー構成を読み込みます。MCPクライアントがサーバープロセスの起動と停止を管理します。

構成

サーバーは、MCP 設定のenvオブジェクトを介して渡される環境変数を構成に使用します。

GOOGLE_GEMINI_API_KEY (必須): Google AI Studio から取得した API キー。
GOOGLE_GEMINI_MODEL (オプション): デフォルトのGeminiモデル名を指定します（例: gemini-1.5-flash 、 gemini-1.0-pro ）。設定されている場合、モデル名を必要とするツール（ gemini_generateContent 、 gemini_startChatなど）は、ツール呼び出しでmodelNameパラメータが省略されたときに、このデフォルトを使用します。これにより、主に1つのモデルを使用する場合のクライアント呼び出しが簡素化されます。この環境変数が設定されていない場合、これらのツールではmodelNameパラメータが必須になります。使用可能なモデル名については、Google AIのドキュメントをご覧ください。

利用可能なツール

このサーバーは以下のMCPツールを提供します。パラメータスキーマは検証と記述のためにZodを使用して定義されています。

**オプションパラメータに関する注意：**多くのツールは、複雑なオプションパラメータ（例： generationConfig 、 safetySettings 、 toolConfig 、 history 、 functionDeclarations 、 contents ）を受け入れます。これらのパラメータは通常、基盤となる@google/genai SDK で定義された型を反映した構造を持つオブジェクトまたは配列です。これらの複雑なパラメータの正確な構造と利用可能なフィールドについては、以下を参照してください。1. このプロジェクトの対応するsrc/tools/*Params.tsファイル。2. 公式のGoogle AI JS SDK ドキュメント。

コア世代

gemini_generateContent
- *説明:*プロンプトから非ストリーミングテキストコンテンツを生成します。
- 必須パラメータ: prompt (文字列)
- オプションパラメータ: modelName (文字列)、 generationConfig (オブジェクト)、 safetySettings (配列)
gemini_generateContentStream
- *説明:*ストリーミングを介してテキストコンテンツを生成します。(注: 現在の実装では回避策が使用され、完全なテキストを返す前にすべてのチャンクが収集されます)。
- 必須パラメータ: prompt (文字列)
- オプションパラメータ: modelName (文字列)、 generationConfig (オブジェクト)、 safetySettings (配列)

関数呼び出し

gemini_functionCall
- *説明:*プロンプトと関数宣言をモデルに送信し、テキスト応答または要求された関数呼び出しオブジェクト (JSON 文字列として) を返します。
- 必須パラメータ: prompt (文字列)、 functionDeclarations (配列)
- オプションパラメータ: modelName (文字列)、 generationConfig (オブジェクト)、 safetySettings (配列)、 toolConfig (オブジェクト)

ステートフルチャット

gemini_startChat
- *説明:新しいステートフルチャットセッションを開始し、一意のsessionIdを返します。\n *必須パラメータ:*なし
- オプションパラメータ: modelName (文字列)、 history (配列)、 tools (配列)、 generationConfig (オブジェクト)、 safetySettings (配列)
gemini_sendMessage
- 説明:既存のチャットセッション内でメッセージを送信します。\n *必須パラメータ: sessionId (文字列)、 message (文字列)
- オプションパラメータ: generationConfig (オブジェクト)、 safetySettings (配列)、 tools (配列)、 toolConfig (オブジェクト)
gemini_sendFunctionResult
- 説明:関数実行の結果をチャットセッションに送り返します。\n *必須パラメータ: sessionId (文字列)、 functionResponses (配列)
- オプションパラメータ: generationConfig (オブジェクト)、 safetySettings (配列)

ファイル処理（Google AI Studio キーが必要）

gemini_uploadFile
- 説明:ローカルパスからファイルをアップロードします。\n**必須パラメータ: filePath (文字列 -絶対パスである必要があります)\n オプションパラメータ: displayName (文字列)、 mimeType (文字列)
gemini_listFiles
- *説明:以前にアップロードされたファイルを一覧表示します。\n *必須パラメータ:*なし
- オプションパラメータ: pageSize (数値)、 pageToken (文字列 - 注: 現在、 pageTokenが確実に返されない可能性があります)。
gemini_getFile
- 説明:特定のアップロードされたファイルのメタデータを取得します。\n *必須パラメータ: fileName (文字列 - 例: files/abc123xyz )
gemini_deleteFile
- 説明:アップロードされたファイルを削除します。\n *必須パラメータ: fileName (文字列 - 例: files/abc123xyz )

キャッシュ（Google AI Studio キーが必要）

gemini_createCache
- 説明:互換性のあるモデル (例: gemini-1.5-flash ) のキャッシュされたコンテンツを作成します。\n *必須パラメータ: contents (配列)
- オプションパラメータ: modelName (文字列)、 displayName (文字列)、 systemInstruction (オブジェクト)、 ttl (文字列 - 例: '3600s')
gemini_listCaches
- *説明:既存のキャッシュされたコンテンツを一覧表示します。\n *必須パラメータ:*なし
- オプションパラメータ: pageSize (数値)、 pageToken (文字列 - 注: 現在、 pageTokenが確実に返されない可能性があります)。
gemini_getCache
- 説明:特定のキャッシュされたコンテンツのメタデータを取得します。\n *必須パラメータ: cacheName (文字列 - 例: cachedContents/abc123xyz )
gemini_updateCache
- 説明:キャッシュされたコンテンツのメタデータ (TTL、displayName) を更新します。\n *必須パラメータ: cacheName (文字列)
- オプションパラメータ: ttl (文字列)、 displayName (文字列)
gemini_deleteCache
- 説明:キャッシュされたコンテンツを削除します。\n *必須パラメータ: cacheName (文字列 - 例: cachedContents/abc123xyz )

使用例

MCP クライアント (Cline など) がuse_mcp_tool形式を使用してこれらのツールを呼び出す方法の例を次に示します。

例1: シンプルなコンテンツ生成（デフォルトモデルを使用）

<use_mcp_tool>
  <server_name>gemini-server</server_name>
  <tool_name>gemini_generateContent</tool_name>
  <arguments>
    {
      "prompt": "Write a short poem about a rubber duck."
    }
  </arguments>
</use_mcp_tool>

例2: コンテンツ生成（モデルと設定の指定）

<use_mcp_tool>
  <server_name>gemini-server</server_name>
  <tool_name>gemini_generateContent</tool_name>
  <arguments>
    {
      "modelName": "gemini-1.0-pro",
      "prompt": "Explain the concept of recursion in programming.",
      "generationConfig": {
        "temperature": 0.7,
        "maxOutputTokens": 500
      }
    }
  </arguments>
</use_mcp_tool>

例3: チャットの開始と継続

チャットを開始:

<use_mcp_tool>
  <server_name>gemini-server</server_name>
  <tool_name>gemini_startChat</tool_name>
  <arguments>
    {}
  </arguments>
</use_mcp_tool>

(応答にsessionId: "some-uuid-123"が含まれていると仮定)

メッセージを送信:

<use_mcp_tool>
  <server_name>gemini-server</server_name>
  <tool_name>gemini_sendMessage</tool_name>
  <arguments>
    {
      "sessionId": "some-uuid-123",
      "message": "Hello! Can you tell me about the Gemini API?"
    }
  </arguments>
</use_mcp_tool>

例4: ファイルのアップロード

<use_mcp_tool>
  <server_name>gemini-server</server_name>
  <tool_name>gemini_uploadFile</tool_name>
  <arguments>
    {
      "filePath": "C:\\Users\\YourUser\\Documents\\my_document.txt", // IMPORTANT: Use absolute path with escaped backslashes if needed
      "displayName": "My Document"
    }
  </arguments>
</use_mcp_tool>

エラー処理

サーバーは、ツールの実行が失敗した場合に、MCP標準のMcpError型を使用して構造化されたエラーを返すことを目的としています。このオブジェクトには通常、以下の情報が含まれます。

code : エラーの種類を示すErrorCode列挙値 (例: InvalidParams 、 InternalError 、 PermissionDenied 、 NotFound )。
message : 人間が読める形式のエラーの説明。
details : (オプション) トラブルシューティングのために、基礎となる Gemini SDK エラーのより具体的な情報 (安全性ブロックの理由や API エラーメッセージなど) を含む可能性のあるオブジェクト。

一般的なエラーのシナリオ:

**無効な API キー:**多くの場合、認証の失敗を示す詳細を含むInternalErrorが発生します。
無効なパラメータ: InvalidParamsになります (例: 必須フィールドが欠落している、データ型が間違っている)。
**安全ブロック:**ブロック理由または終了理由としてSAFETYを示す詳細を含むInternalErrorが発生する可能性があります。
ファイル/キャッシュが見つかりません: SDK がエラーを表示する方法に応じて、 NotFoundまたはInternalErrorが発生する可能性があります。
レート制限: ResourceExhaustedまたはInternalErrorが発生する可能性があります。

トラブルシューティングを行うときは、返されたMcpErrorのmessageとdetailsフィールドで具体的な手がかりを確認してください。

発達

このサーバーは、プロジェクトの.clinerulesおよび内部ドキュメントに記載されている標準的なMCPサーバー構造に準拠しています。主なパターンは次のとおりです。

サービスレイヤー ( src/services ): @google/genai SDK とのやり取りをカプセル化し、MCP の詳細から切り離します。
**ツールレイヤー ( src/tools ):**サービスレイヤー機能を MCP ツールに適合させ、パラメーターマッピングとエラー変換を処理します。
**Zod スキーマ ( src/tools/*Params.ts ):**ツールパラメータの定義、検証の提供、LLM の相互作用に重要な詳細な説明の生成に広く使用されます。
構成 ( src/config ): ConfigurationManagerによる集中管理。
**型 ( src/types ):**明確な TypeScript 定義。

既知の問題

gemini_generateContentStream回避策として、すべてのチャンクを収集してからフルテキストを返します。MCPクライアントへの真のストリーミングはまだ実装されていません。
gemini_listFilesとgemini_listCaches 、SDK の Pager オブジェクトの反復処理の制限により、 nextPageToken確実に返さない可能性があります。
gemini_uploadFile 、サーバー環境から実行する場合、絶対ファイルパスを必要とします。
Vertex AI ではファイル処理とキャッシュ API はサポートされておらず、Google AI Studio API キーのみがサポートされています。

MCP Gemini Server

Integrations