Mcp Server

MCP Gmail Server

このリポジトリでは、Gmail 用の MCP（Model Context Protocol）サーバーを提供しています。定義済みのツール（list_unread、search_emails）を使い、MCP プロトコル経由で Gmail アカウントを操作できます。Google の OAuth2 認証を処理し、Open WebUI やその他の MCP クライアントと連携するための asyncio ベースのサーバーを公開します。

機能

• list_unread：未読の Gmail メッセージのスニペットを取得します。
• search_emails：Gmail の検索クエリ（例：from:[email protected]）でメールを検索します。
• トークンのキャッシュ機能を備えたシームレスな OAuth2 フロー。
• MCP クライアント（例：Open WebUI）と互換性のある asyncio ベースのサーバー。

---

MCP とは？

Model Context Protocol（MCP）は、アプリケーションが大規模言語モデル（LLM）にコンテキストを提供する方法を定義するオープン標準です。MCP は、ハードウェアにおける USB-C のような標準化されたインターフェースと考えることができます。AI モデルがさまざまなツールやデータソースにシームレスに接続できるようにします。

---

mcpo を使う理由

MCP サーバーは強力ですが、通常は標準入力／出力（stdio）で通信するため、制約が生じることがあります。

• 異なる環境間での安全性に欠けます。
• 多くの最新ツール、UI、プラットフォームと互換性がありません。
• 認証、ドキュメント、エラー処理などの機能が不足しています。

mcpo（MCP-to-OpenAPI プロキシ）は、次の方法でこれらの問題に対処します。

• MCP ツールを、安全でスケーラブルな HTTP エンドポイントでラップします。
• 既存の OpenAPI ツール、SDK、クライアントとすぐに連携できるようにします。
• 各ツールのインタラクティブな OpenAPI ドキュメントを自動生成します。
• プレーンな HTTP を使用するため、ソケットの設定やプラットフォーム固有のコードが不要です。

これにより、既存の MCP サーバーコードを変更せずに、AI ツールをクラウドにデプロイし、Open WebUI のようなウェブインターフェースと連携させ、セキュリティとスケーラビリティを向上できます。

---

mcpo 経由で MCP Gmail Server を公開する

mcpo を使って MCP Gmail Server を OpenAPI 経由で公開するには、次の手順に従います。

1. mcpo をインストールします：

   pip を使用する場合：

   pip install mcpo
   

   または、uv を使用する場合（起動が速いため推奨）：

   uv pip install mcpo
   

2. mcpo で MCP Gmail Server を実行します：

   mcpo --port 8000 -- uv run gmail-server
   

   このコマンドにより、ポート 8000 で mcpo プロキシが起動し、その背後で Gmail MCP サーバーが実行されます。

3. OpenAPI ドキュメントにアクセスします：

   起動したら、ブラウザーで http://localhost:8000/docs にアクセスし、Gmail ツール用に自動生成された OpenAPI ドキュメントを確認します。

4. Open WebUI と連携します：

   Open WebUI で、新しい OpenAPI ツールサーバーのエンドポイント（例：http://localhost:8000）を指定して追加します。これにより、定義済みのツールを使って Open WebUI のインターフェースから Gmail アカウントを操作できます。

---

mcpo を MCP Gmail Server と連携させることで、アクセス性、セキュリティ、最新のツールやプラットフォームとの互換性が向上し、標準化された API を通じて Gmail アカウントをシームレスに操作できます。

---

前提条件

• Python 3.13 以降
• uv パッケージマネージャー
• Google アカウント
• Google Cloud Console でプロジェクトと OAuth 認証情報を作成できる権限

プロジェクト構成

├── mcp_server/
│   ├── __init__.py       # Package initialization
│   └── gmail/
│       ├── __init__.py   # Module initialization
│       └── server.py     # Main server implementation
├── tests/
│   ├── __init__.py
│   └── test_gmail_server.py  # Test suite for Gmail server
├── secrets/
│   ├── credentials.json  # OAuth2 client credentials (downloaded)
│   └── token.json        # Cached user tokens (auto-created)
├── pyproject.toml        # Project metadata and dependencies
├── pytest.ini           # Pytest configuration
├── run_tests.sh         # Script to run tests with uv
├── Dockerfile           # Docker configuration
└── README.md            # This documentation

Gmail API 認証情報の設定

1. Google Cloud Console にアクセスします。
2. 新しいプロジェクトを作成するか、既存のプロジェクトを選択します。
3. APIs & Services > Library で Gmail API を有効にします。
4. APIs & Services > OAuth consent screen で、External の同意画面を設定します。
   • アプリ名：MCP Gmail Server
   • メールアドレスをテストユーザーとして追加します（サーバーは公開されません）。
5. APIs & Services > Credentials で、Create Credentials > OAuth client ID をクリックします。
   • アプリケーションの種類：Desktop app
   • JSON ファイルをダウンロードします。
6. ダウンロードしたファイルの名前を credentials.json に変更し、secrets/ ディレクトリに配置します。

インストール

1. このリポジトリをクローンします：

2. まだインストールしていない場合は、uvをインストールします：

   pipx install uv
   

3. uvを使用して仮想環境を作成し、有効化します：

   # Create a virtual environment
   uv venv
   
   # Activate the virtual environment
   # On Unix/macOS:
   source .venv/bin/activate
   
   # On Windows:
   .\.venv\Scripts\activate
   

4. uvを使用して依存関係をインストールします：

   # Install the package in development mode
   uv pip install -e .
   

設定

• secrets/credentials.jsonファイルが存在することを確認します。
• 初回実行時に、ブラウザーでアプリを認証するよう求められます。その後、secrets/token.jsonファイルが作成されます。

サーバーの実行

次のコマンドでMCPサーバーを起動します：

# Run directly with uv
uv run gmail-server

# Alternative: Run with MCP OpenAPI Proxy
uvx mcpo --port 8000 --api-key "your-api-key" -- uv run gmail-server

サーバーが実行中で、MCPクライアントからの接続を待ち受けていることを示す出力が表示されます。

使い方

• MCPに準拠したクライアント（例：Open Web UI）を接続します。
• 次のツール／アクションを使用します：
  • list_unread：未読メールの抜粋を返します。
  • search_emails：指定されたGmailクエリに一致するメールを返します。

Dockerの設定

このプロジェクトには、コンテナ化用のDockerfileが含まれています：

1. Dockerイメージをビルドします：

   docker build -t gmail-mcp-server .
   

2. Dockerコンテナを実行します：

   docker run -p 8000:8000 \
     -e API_KEY="your-secure-api-key" \
     gmail-mcp-server
   

Dockerの設定詳細

• ベースイメージ：Python 3.13-slim
• 依存関係：uvを使用してインストールされます
• ボリュームのマウント：/app/secretsにGoogle OAuthの認証情報を配置します
• 環境変数：
  • API_KEY：MCP OpenAPIプロキシのセキュリティキー（デフォルト："top-secret"）
• ポート：MCP OpenAPIプロキシ用にポート8000を公開します

ライセンス

このプロジェクトはMITライセンスの下でライセンスされています。詳細については、LICENSEファイルをご覧ください。