Mcp Cosmosdb Sql

MCP CosmosDB - Azure CosmosDB MCP サーバー

Azure CosmosDB データベース操作のための包括的な Model Context Protocol（MCP） サーバーです。このサーバーは、MCP プロトコルを通じて、ドキュメントデータベースの分析、コンテナーの検出、データのクエリ、CRUD 操作を行うための 13 個の強力なツールを提供します。

✨ 特長

• 🔗 複数接続のサポート：単一の MCP インスタンスから複数の CosmosDB アカウント／データベースを管理できます
• 🔒 セキュリティを最優先：書き込み操作はデフォルトで無効です
• ⚡ 高パフォーマンス：接続のキャッシュと最適化されたクエリ
• 📊 13 個のツール：データベース操作の完全なセット

🚀 クイックスタート

前提条件

• Node.js 18+ および npm
• 接続文字列を持つ Azure CosmosDB データベース
• MCP 対応クライアント（Claude Desktop、Cursor IDE など）

⚙️ 設定

設定の優先順位

サーバーは、次の 3 つの設定方法を優先順位順にサポートします。

優先順位	方法	環境変数	説明
1️⃣	外部ファイル	COSMOS_CONNECTIONS_FILE	接続配列を含む JSON ファイルへのパス
2️⃣	JSON 文字列	COSMOS_CONNECTIONS	接続配列をインラインで記述した JSON
3️⃣	単一接続	COSMOS_CONNECTION_STRING + COSMOS_DATABASE_ID	従来の単一接続モード

🔒 セキュリティ設定

変数	説明	デフォルト
DB_ALLOW_MODIFICATIONS	書き込み操作（作成、更新、削除、アップサート）の有効／無効を切り替えます	false

⚠️ 重要：安全のため、デフォルトではすべての書き込み操作が無効になっています。書き込み操作が必要な場合に限り、DB_ALLOW_MODIFICATIONS=true を設定してください。

---

📦 インストール方法

方法 1：外部ファイルを使った複数接続（推奨）✅

接続ファイル（例：cosmos-connections.json）を作成します。

[
  {
    "id": "production",
    "connectionString": "AccountEndpoint=https://myapp-prod.documents.azure.com:443/;AccountKey=...;",
    "databaseId": "ProductionDB",
    "allowModifications": false,
    "description": "Production database (read-only)"
  },
  {
    "id": "development",
    "connectionString": "AccountEndpoint=https://myapp-dev.documents.azure.com:443/;AccountKey=...;",
    "databaseId": "DevDB",
    "allowModifications": true,
    "description": "Development database"
  },
  {
    "id": "analytics",
    "connectionString": "AccountEndpoint=https://analytics.documents.azure.com:443/;AccountKey=...;",
    "databaseId": "AnalyticsDB",
    "allowModifications": false,
    "description": "Analytics database"
  }
]

MCP クライアントを設定します。

{
  "mcpServers": {
    "cosmosdb": {
      "command": "npx",
      "args": ["-y", "mcpcosmosdb@latest"],
      "env": {
        "COSMOS_CONNECTIONS_FILE": "/path/to/cosmos-connections.json"
      }
    }
  }
}

方法 2：インライン JSON を使った複数接続

{
  "mcpServers": {
    "cosmosdb": {
      "command": "npx",
      "args": ["-y", "mcpcosmosdb@latest"],
      "env": {
        "COSMOS_CONNECTIONS": "[{\"id\":\"prod\",\"connectionString\":\"AccountEndpoint=https://...\",\"databaseId\":\"ProdDB\",\"allowModifications\":false},{\"id\":\"dev\",\"connectionString\":\"AccountEndpoint=https://...\",\"databaseId\":\"DevDB\",\"allowModifications\":true}]"
      }
    }
  }
}

方法 3：単一接続（従来方式）

読み取り専用モード（デフォルト - 安全）：

{
  "mcpServers": {
    "cosmosdb": {
      "command": "npx",
      "args": ["-y", "mcpcosmosdb@latest"],
      "env": {
        "COSMOS_CONNECTION_STRING": "AccountEndpoint=https://your-cosmos-account.documents.azure.com:443/;AccountKey=your-account-key-here;",
        "COSMOS_DATABASE_ID": "your-database-name"
      }
    }
  }
}

書き込み操作を有効にする場合：

{
  "mcpServers": {
    "cosmosdb": {
      "command": "npx",
      "args": ["-y", "mcpcosmosdb@latest"],
      "env": {
        "COSMOS_CONNECTION_STRING": "AccountEndpoint=https://your-cosmos-account.documents.azure.com:443/;AccountKey=your-account-key-here;",
        "COSMOS_DATABASE_ID": "your-database-name",
        "DB_ALLOW_MODIFICATIONS": "true"
      }
    }
  }
}

方法 4：GitHub から NPX を使用

{
  "mcpServers": {
    "cosmosdb": {
      "command": "npx",
      "args": ["-y", "hendrickcastro/MCPCosmosDB"],
      "env": {
        "COSMOS_CONNECTION_STRING": "AccountEndpoint=https://...;AccountKey=...;",
        "COSMOS_DATABASE_ID": "your-database-name"
      }
    }
  }
}

方法 5：ローカル開発

git clone https://github.com/hendrickcastro/MCPCosmosDB.git
cd MCPCosmosDB
npm install && npm run build

{
  "mcpServers": {
    "cosmosdb": {
      "command": "node",
      "args": ["path/to/MCPCosmosDB/dist/server.js"],
      "env": {
        "COSMOS_CONNECTIONS_FILE": "/path/to/cosmos-connections.json"
      }
    }
  }
}

---

🛠️ 利用可能なツール（合計 13 個）

🔗 接続管理

ツール	説明
mcp_list_connections	設定済みのすべての接続とその状態を一覧表示します

📖 読み取り操作（常に利用可能）

ツール	説明
mcp_list_databases	CosmosDB アカウント内のすべてのデータベースを一覧表示します
mcp_list_containers	現在のデータベース内のすべてのコンテナーを一覧表示します
mcp_get_container_definition	コンテナーの詳細な構成（パーティションキー、インデックス作成ポリシー、スループット）を取得します
mcp_get_container_stats	コンテナーの統計情報（ドキュメント数、サイズ、パーティション分布）を取得します
mcp_cosmos_query	パラメーターとパフォーマンス指標を指定して SQL クエリを実行します
mcp_get_documents	オプションのフィルタリングを使用してドキュメントを取得します
mcp_get_document_by_id	ID とパーティションキーを指定して、特定のドキュメントを取得します
mcp_analyze_schema	コンテナー内のドキュメントスキーマ構造を分析します

✏️ 書き込み操作（allowModifications: true が必要）

ツール	説明
mcp_create_document	コンテナーに新しいドキュメントを作成します
mcp_update_document	既存のドキュメントを更新（置換）します
mcp_delete_document	コンテナーからドキュメントを削除します
mcp_upsert_document	ドキュメントを作成または更新します（アップサート操作）

🛡️ セキュリティに関する注意：書き込み操作はデフォルトでブロックされます。接続設定で allowModifications: true を設定するか、単一接続モードでは DB_ALLOW_MODIFICATIONS=true を設定してください。

---

📋 使用例

マルチ接続の使用

// List all available connections
const connections = await mcp_list_connections();
// Returns: { connections: [{id: "prod", databaseId: "ProdDB", isConnected: true}, ...] }

// Query specific connection using connection_id
const prodData = await mcp_cosmos_query({
  connection_id: "production",
  container_id: "users",
  query: "SELECT TOP 10 c.id, c.name FROM c ORDER BY c._ts DESC"
});

const devData = await mcp_cosmos_query({
  connection_id: "development",
  container_id: "users",
  query: "SELECT TOP 10 c.id, c.name FROM c ORDER BY c._ts DESC"
});

コンテナーの分析

// List all containers (uses default connection if connection_id not specified)
const containers = await mcp_list_containers({
  connection_id: "production"
});

// Get container definition
const containerDef = await mcp_get_container_definition({ 
  connection_id: "production",
  container_id: "users" 
});

// Get container statistics
const stats = await mcp_get_container_stats({ 
  connection_id: "production",
  container_id: "users",
  sample_size: 1000
});

データのクエリ

⚠️ 重要：常に TOP N を使用し、取得するフィールドを指定してください。SELECT * は絶対に使用しないでください。大規模なコンテナーではタイムアウトや RU 消費量の増加を引き起こします。

// ✅ CORRECT: Using TOP and specific fields
const result = await mcp_cosmos_query({
  connection_id: "production",
  container_id: "products",
  query: "SELECT TOP 50 c.id, c.name, c.price FROM c WHERE c.category = @category",
  parameters: { category: "electronics" }
});

// ❌ WRONG: SELECT * without TOP (will timeout on large containers)
// query: "SELECT * FROM c WHERE c.category = @category"

// Get documents with simple filters
const documents = await mcp_get_documents({
  connection_id: "production",
  container_id: "orders",
  filter_conditions: { status: "completed" },
  order_by: "_ts",
  order_direction: "DESC",
  limit: 100
});

ドキュメント操作

// Get specific document by ID
const document = await mcp_get_document_by_id({
  connection_id: "production",
  container_id: "users",
  document_id: "user-123",
  partition_key: "user-123"
});

// Analyze schema
const schema = await mcp_analyze_schema({
  connection_id: "production",
  container_id: "products",
  sample_size: 500
});

CRUD 操作（allowModifications: true が必要）

// Create a new document
const created = await mcp_create_document({
  connection_id: "development",  // Use a connection with write access
  container_id: "users",
  document: {
    id: "user-456",
    email: "[email protected]",
    name: "John Doe",
    status: "active"
  },
  partition_key: "user-456"
});

// Update a document (full replacement)
const updated = await mcp_update_document({
  connection_id: "development",
  container_id: "users",
  document_id: "user-456",
  document: {
    id: "user-456",
    email: "[email protected]",
    name: "John Doe",
    status: "inactive"
  },
  partition_key: "user-456"
});

// Upsert a document (create or update)
const upserted = await mcp_upsert_document({
  connection_id: "development",
  container_id: "users",
  document: {
    id: "user-789",
    email: "[email protected]",
    name: "Jane Doe"
  },
  partition_key: "user-789"
});

// Delete a document
const deleted = await mcp_delete_document({
  connection_id: "development",
  container_id: "users",
  document_id: "user-456",
  partition_key: "user-456"
});

---

🔧 接続ファイルのスキーマ

interface ConnectionConfig {
  id: string;                    // Unique identifier for the connection
  connectionString: string;      // CosmosDB connection string
  databaseId: string;            // Database ID to connect to
  allowModifications?: boolean;  // Enable write operations (default: false)
  description?: string;          // Optional description
}

cosmos-connections.json の例：

[
  {
    "id": "athlete",
    "connectionString": "AccountEndpoint=https://dbsqlcosmosathlete.documents.azure.com:443/;AccountKey=...;",
    "databaseId": "data",
    "allowModifications": false,
    "description": "Athlete data"
  },
  {
    "id": "events",
    "connectionString": "AccountEndpoint=https://dbsqlcosmosevents.documents.azure.com:443/;AccountKey=...;",
    "databaseId": "events",
    "allowModifications": false,
    "description": "Events data"
  }
]

---

🚨 トラブルシューティング

接続の問題：

• 無効な接続文字列：接続文字列の形式に AccountEndpoint と AccountKey が含まれていることを確認してください
• データベースが見つからない：databaseId が既存のデータベースと一致していることを確認してください
• リクエストのタイムアウト：COSMOS_MAX_RETRY_WAIT_TIME を増やすか、ネットワークを確認してください

クエリの問題：

• クエリのタイムアウト：結果を制限するには TOP N を使用し、必要なフィールドだけを指定して、SELECT * は避けてください
• クロスパーティションクエリが必要：クエリパラメーターで enable_cross_partition: true を設定してください
• パーティションキーが必要：単一パーティション操作では partition_key を指定してください

マルチ接続の問題：

• 接続が見つからない：mcp_list_connections を使用して利用可能な接続 ID を確認してください
• データベースが違う：connection_id パラメーターが正しい接続を指していることを確認してください

書き込み操作がブロックされる：

• エラー：「Database modifications are disabled」：接続設定で allowModifications: true を設定するか、DB_ALLOW_MODIFICATIONS=true を設定してください
• これは安全機能です。書き込み操作はデフォルトで無効になっています

CosmosDB Emulator：

1. Azure CosmosDB Emulator をインストールします
2. ポート 8081 でエミュレーターを起動します
3. デフォルトのエミュレーター接続文字列を使用します
4. テスト用のデータベースとコンテナーを作成します

---

🧪 開発

npm test          # Run tests
npm run build     # Build project
npm start         # Development mode

🏗️ アーキテクチャ

プロジェクト構成：

src/
├── tools/                    # Tool implementations
│   ├── containerAnalysis.ts  # Container operations
│   ├── dataOperations.ts     # Data queries & CRUD
│   └── types.ts              # Type definitions
├── db.ts                     # CosmosDB connection & multi-connection management
├── server.ts                 # MCP server setup
└── tools.ts                  # Tool definitions

主な機能：

• ⚡ 接続のキャッシュとプーリング
• 🔗 マルチ接続管理
• 🛡️ 包括的なエラー処理
• 🔒 接続ごとの書き込み操作の保護
• 📊 パフォーマンス指標とリクエスト料金
• 🔧 柔軟な構成オプション
• 📋 インテリジェントなスキーマ分析

---

📝 重要な注意事項

• クエリのベストプラクティス：常に TOP N を使用してフィールドを指定し、SELECT * は使用しないでください
• コンテナー ID：CosmosDB に登録されている正確な名前を使用してください
• パーティションキー：最適なパフォーマンスと CRUD 操作のために必須です
• クロスパーティションクエリ：コストが高くなる場合があります。フィルターを使用してください
• リクエスト料金：RU の消費量を監視してください
• セキュリティ：接続文字列は安全に保管してください（外部ファイルを使用してください）
• 書き込み保護：必要な接続に対してのみ有効にしてください

---

🤝 コントリビューション

1. リポジトリをフォークします
2. 機能ブランチを作成します（git checkout -b feature/name）
3. 変更を加え、テストを追加します
4. テストが成功することを確認します（npm test）
5. 変更をコミットします（git commit -m 'Add feature'）
6. プッシュしてプルリクエストを作成します

📄 ライセンス

MIT License の詳細については、LICENSE ファイルをご覧ください。

🏷️ タグとキーワード

データベース： cosmosdb azure-cosmosdb nosql document-database database-analysis database-tools azure database-management database-operations data-analysis multi-database

MCP と AI： model-context-protocol mcp-server mcp-tools ai-tools claude-desktop cursor-ide anthropic llm-integration ai-database intelligent-database

テクノロジー： typescript nodejs npm-package cli-tool database-client nosql-client database-sdk rest-api json-api database-connector

機能： container-analysis document-operations sql-queries schema-analysis query-execution database-search data-exploration database-insights partition-management throughput-analysis crud-operations document-crud multi-connection

ユースケース： database-development data-science business-intelligence database-migration schema-documentation performance-analysis data-governance database-monitoring troubleshooting automation

🙏 謝辞

• Model Context Protocol SDK
• @azure/cosmos
• MCPQL に着想を得ています

🎯 MCP CosmosDB は、Model Context Protocol を通じて Azure CosmosDB データベースを包括的に分析します。CosmosDB を扱う開発者やデータアナリストに最適です！ 🚀