Cosmos DB MCP Server を使って自然言語でデータベースを操作する

Posted on 2025-03-31

AI Agent 全盛の時代に入って Cosmos DB と GenAI を組み合わせた新しい利用法が次々と登場しています。その中でも最近特に注目しているのが、先日 OSS として公開された「Azure Cosmos DB MCP Server」です。
本記事では、Cosmos DB の MCP Server を PC 環境にセットアップし、Claude Desktop を MCP Client として Cosmos DB を LLM を介して利用する方法を紹介します。公式リポジトリでは GitHub Copilot Agent Mode を使った方法を中心に書かれているので、ここではより手軽な Claude Desktop を使った方法で説明します。

Azure Cosmos DB MCP Server とは?

Azure Cosmos DB MCP Server は、Cosmos DB に対して自然言語での問い合わせを可能にする MCP Server です。データベース操作を SQL や複雑なクエリではなく、人間が自然に話す言葉で行えるようになります。MCP の使い道はいろいろあると思いますが、このようないわゆる Text-to-SQL の分野とはとても相性が良いと思っています。
GitHub 上で公開されているリポジトリはこちらです。

azure-cosmos-mcp-server

Cosmos DB の準備

まずは、Azure Portal で Cosmos DB を準備します。Cosmos DB は NoSQL API でアカウントを作成して下さい（1 サブスクリプションあたり 1000RU までは無償で利用できる枠があります）。もしくはもともと所有しているデータがあればそれを使っても OK です。

リポジトリに準備されているサンプルデータを利用するのであれば、データベース名を toyota、コンテナ名を vehicles にしておきます（RU は Auto Scale の 1000 をおすすめします）。
リポジトリの dataset ディレクトリに vehicles.json があるのでそれを Cosmos DB にインポートします。Azure Portal の Cosmos DB で Data Explorer を開き、「vehicles」コンテナを選択した状態で上部のメニューから Upload Items を選択すると JSON に入っているデータを一括でインポートできます。

MCP Server のセットアップ

ここでは Claude Desktop を使って MCP Server に接続したいと思います。Cosmos DB MCP Server は Node.js で実装されているので、ローカルに Node.js の実行環境があることが前提になります。

まず、リポジトリをクローンします。

git clone https://github.com/AzureCosmosDB/azure-cosmos-mcp-server.git
cd azure-cosmos-mcp-server

続いて必要なライブラリをインストールして正しくビルドできることを確認します。

npm install
npm run build

ちなみにここで npm start を実行しても環境変数が設定されていないためエラーになります（今回は環境変数の設定は Claude Desktop 側で行います）。
これで MCP Server 側の準備は完了です。

Claude Desktop (MCP Client) の設定

今回は Claude Desktop を MCP Client として利用するので、Cosmos DB MCP Server を正しく起動するための環境変数を設定します。claude_desktop_config.json で以下のようにコマンドと環境変数を設定してください。

{
  "mcpServers": {
    "cosmosdb": {
      "command": "node",
      "args": ["C:\\{ソースコードをクローンしたパス}\\azure-cosmos-mcp-server\\dist\\index.js"],
      "env": {
        "COSMOSDB_URI": "https://cosmos-{Cosmos DB アカウント名}.documents.azure.com:443/",
        "COSMOSDB_KEY": "{Cosmos DB アカウントのキー}",
        "COSMOS_DATABASE_ID": "toyota",
        "COSMOS_CONTAINER_ID": "vehicles"
      }
    }
  }
}

claude_desktop_config.json の設定では以下に気を付けてください。

Claude Desktop は開発者モードを有効にしておく
command では MCP Server を起動するための node コマンドを指定します。Node 切り替えツールを入れている場合で、Node.js の実行コマンドが node でない場合はフルパスを指定してください。
args では MCP Server の実行ファイル（ npm run build で生成された JS ファイル）のパスを指定します（Windows の場合は C:\\ で始まるフルパスを指定してください）
env では Cosmos DB の接続情報を指定します（キー名は変えないで下さい）。URI と KEY は Azure Portal の Cosmos DB の「Keys」タブから取得できます。データベース名とコンテナ名は Data Explorer で確認できます。

Claude Desktop を再起動して以下のように MCP Server が正しく起動していることを確認してください。
チャット入力欄下側に斧のアイコンが出てくるのでそれをクリックすると以下のように Cosmos DB MCP Server で実装されているツールが表示されます。

Claude Desktop を使った自然言語クエリの例

Claude Desktop（MCP Client）を使って MCP Server に自然言語でクエリを送信します。以下のように自然言語で質問を投げかけると、MCP Server が Cosmos DB に対して適切なクエリを実行し、結果を返してくれます。

例えば、以下のように少しあいまいな言い方で質問しても、内部で NoSQL のクエリに変換して正しくデータを返してくれました。

現在、Cosmos DB MCP Server では、読み取り、クエリ、追加、更新の 4 つのツールが用意されており、質問がそのどれかにマッチするように LLM が自然言語をクエリに変換してくれます。もし定義として不足するクエリがあるようであれば、MCP Server 側にツールを追加すればやれることの幅が広がるはずです（例: 消費した RU を返すツールなど）。

このように、自然言語を使うことで複雑なデータベース操作がシンプルに実現可能になります。特に、Cosmos DB の NoSQL で使う構文は、一般的な SQL とは少し異なる部分があるので、自然言語でクエリができるメリットは大きいと思います。

Azure Cosmos DB MCP Server はまだ登場したばかりです。おそらく不具合や不足している機能もあると思うので、気になったことがあれば Issue や PR を発行すると良いと思います（私も何件か貢献しました）。今後のアップデートに期待したいですね。