MCP server for Azure Cosmos DB using the Go SDK

Azure Cosmos DB 向け MCP サーバーの Go 実装

これは、Azure SDK for Go と公式の MCP Go SDK を使用した、Azure Cosmos DB 向け MCP サーバーの Go 実装です。

Azure Cosmos DB サービスと vNext emulator で動作し、Azure Cosmos DB を操作するための以下のツールを提供します。

1. データベースの一覧表示：Cosmos DB アカウント内のすべてのデータベースの一覧を取得します。
2. データベースの作成：Cosmos DB アカウントに新しいデータベースを作成します。
3. コンテナーの一覧表示：指定したデータベース内のすべてのコンテナーの一覧を取得します。
4. コンテナーのメタデータの読み取り：指定したコンテナーのメタデータまたは構成の詳細を取得します。
5. コンテナーの作成：定義したパーティションキーを使用して、指定したデータベースに新しいコンテナーを作成します。
6. コンテナーへの項目の追加：データベース内の指定したコンテナーに新しい項目を追加します。
7. 項目の読み取り：ID とパーティションキーを使用して、コンテナーから特定の項目を読み取ります。
8. クエリの実行：パーティションキーによる任意のスコープ指定を使用して、Cosmos DB コンテナーで SQL クエリを実行します。
9. 項目の一括作成：トランザクションバッチ操作を使用して、コンテナーに複数の項目を追加します。

⚠️ このプロジェクトは、Azure MCP Server や Azure Cosmos DB MCP Toolkit に取って代わることを目的としていません。Azure Go SDK と MCP Go SDK を組み合わせて Azure Cosmos DB 向けの AI ツールを構築する方法を紹介する、実験的な学習ツールです。

▶️ GitHub Copilot CLI を使用したデモはこちらです。Visual Studio Code のエージェントモードや、その他の MCP 対応ツール（Claude Code など）でも同様に動作します。

🚀 実行方法

まず、GitHub リポジトリをクローンし、バイナリをビルドします。

git clone https://github.com/abhirockzz/mcp_cosmosdb_go
cd mcp_cosmosdb_go

go build -o mcp_azure_cosmosdb_go main.go

注：MCP サーバーは、Azure Cosmos DB との認証に Azure SDK for Go の DefaultAzureCredential 実装を使用します。つまり、環境変数、マネージド ID、Azure CLI ログインなど、さまざまな方法で認証できます。

上記は、既知のキーを使用した認証を行うローカルエミュレーターには適用されません。

この MCP サーバーは、Streamable HTTP と Stdio の両方のトランスポートをサポートしています。MCP サーバーは、次の 2 つのモードで実行できます。

• HTTP サーバーまたは stdio プロセスとしてローカルマシンで実行
• Azure App Service、Azure Container Apps などに HTTP(s) サーバーとしてデプロイし、リモートエンドポイントで実行

💻 ローカルモード

Streamable HTTP に対応しているため、この MCP サーバーをローカルマシン上で HTTP サーバーとして簡単に実行できます。

Azure CLI（az login）または Azure Developer CLI（azd auth login）を使用してログインしてください。この MCP サーバーは DefaultAzureCredential を使用するため、Azure CLI または Azure Developer CLI にログインしている ID として認証されます。

ログインに使用するユーザープリンシパル（ID）には、データベース、コンテナー、項目に対する CRUD 操作を実行する権限（コントロール プレーンおよびデータ プレーン）が必要です。

🌐 HTTP サーバー

サーバーを起動します。

export COSMOSDB_MCP_SERVER_MODE=http
./mcp_azure_cosmosdb_go

デフォルトでは、ポート 9090 でサーバーが起動します。PORT 環境変数を設定すると、ポートを変更できます。

MCP サーバーの設定方法は、使用する MCP クライアント／ツールによって異なります。VS Code では、mcp.json ファイルを使用してこのサーバーを設定する方法について、こちらの手順を参照してください。

HTTP サーバー用の mcp.json 設定例を以下に示します。

{
  "servers": {
    "mcp_azure_cosmosdb_go_http": {
      "type": "http",
      "url": "http://localhost:9090"
    }
  }
  //other MCP servers...
}

別のポートを設定している場合は、ポートを変更してください。

🖥️ Stdio サーバー

stdio モード用の mcp.json 設定例を以下に示します。

{
  "servers": {
    "mcp_azure_cosmosdb_go_stdio": {
      "type": "stdio",
      "command": "./mcp_azure_cosmosdb_go"
    }
  }
  //other MCP servers...
}

ツールで MCP サーバーを設定したら、デモで示したように、Azure Cosmos DB とのやり取りに使用できます。Claude Code、Claude Desktop などのその他のツールについては、MCP HTTP／stdio サーバーの設定方法を各ツールのドキュメントで確認してください。

大規模言語モデル（LLM）は本質的に非決定的であり、誤りを犯すことがあります。結果やクエリに基づいて判断を下す前に、必ず検証してください。

どちらの場合も、vNext エミュレーターを使用するには、ローカルマシンでエミュレーターが実行中であることを確認してください。docker run -p 8081:8081 -p 1234:1234 mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview

☁️ リモートエンドポイント

この MCP サーバーは、任意のクラウドサービス（Azure App Service、Azure Container Apps など）にデプロイし、HTTP(s) エンドポイントとして公開することもできます。Azure サービスはマネージド ID に対応している必要があります。MCP サーバーは、DefaultAzureCredential の実装を使用して、資格情報を自動的に取得します。

⛔️ この実行モードは推奨されません。テスト目的でのみ使用してください。MCP サーバーはマネージド ID を使用して Azure Cosmos DB に安全にアクセスできますが、クライアントの認証（または認可）はまだ行わないため、エンドポイントにアクセスできる人は誰でも Cosmos DB アカウント上で操作を実行できます。

🧪 ローカルでの開発とテスト

MCP inspector を使用します。make mcp_inspector