Mongo Mcp

Mongo-MCP

英語 | 簡体字中国語

MongoDB 操作用の Machine Chat Protocol（MCP）サービスです。このサービスは、完全な CRUD 操作、管理タスク、高度な機能を通じて、LLM が MongoDB データベースを操作できる包括的なツールセットを提供します。

要件

• Python 3.10 以降
• 稼働中の MongoDB データベースサービス
• プログラムの実行には uv の使用を推奨します

🚀 機能

📊 データベース管理ツール

• list_databases - すべてのデータベースを一覧表示
• create_database - 新しいデータベースを作成
• drop_database - データベースを削除
• get_database_stats - データベースの統計情報を取得

📦 コレクション管理ツール

• list_collections - データベース内のすべてのコレクションを一覧表示
• create_collection - 新しいコレクションを作成（設定は任意）
• drop_collection - コレクションを削除
• rename_collection - コレクション名を変更
• get_collection_stats - コレクションの統計情報を取得

📄 ドキュメントの CRUD 操作

• insert_document - 単一のドキュメントを挿入
• insert_many_documents - 複数のドキュメントを一括挿入
• find_documents - ドキュメントを検索（ソート、プロジェクション、上限設定に対応）
• find_one_document - 単一のドキュメントを検索
• count_documents - クエリに一致するドキュメント数をカウント
• update_document - ドキュメントを更新（単一または一括）
• replace_document - ドキュメントを置換
• delete_document - ドキュメントを削除（単一または一括）

🔍 インデックス管理ツール

• list_indexes - コレクションのすべてのインデックスを一覧表示
• create_index - 通常のインデックスを作成
• create_text_index - テキスト検索インデックスを作成
• create_compound_index - 複合インデックスを作成
• drop_index - インデックスを削除
• reindex_collection - コレクションのすべてのインデックスを再構築

📈 集計操作

• aggregate_documents - 集計パイプライン操作を実行
• distinct_values - フィールドの個別の値を取得

🔧 監視および管理ツール

• get_server_status - MongoDB サーバーのステータスを取得
• get_replica_set_status - レプリカセットのステータスを取得
• ping_database - データベース接続をテスト
• test_mongodb_connection - 包括的な接続テスト
• get_connection_details - 接続情報の詳細を取得

🛠️ 技術スタック

• Python：主要なプログラミング言語
• FastMCP：ツール定義を自動生成する MCP Python SDK
• PyMongo：MongoDB 公式 Python ドライバー
• uv：最新の Python パッケージ管理ツール

使用方法

uvx で直接実行

uvx run mongo-mcp

サーバーは stdio トランスポート方式を使用するため、この方式に対応した MCP クライアントとの統合に適しています。

Cursor の設定例

開発環境として Cursor を使用している場合、ローカルデバッグ用に以下の設定を .cursor/mcp.json ファイルに追加できます。

{
    "mcpServers": {
        "mongo-mcp": {
            "command": "uvx",
            "args": [
                "mongo-mcp"
            ],
            "env": {
                "MONGODB_URI": "mongodb://localhost:27017",
                "MONGODB_DEFAULT_DB": "your_database_name",
                "LOG_LEVEL": "INFO"
            }
        }
    }
}

環境変数

基本設定

• MONGODB_URI：MongoDB 接続文字列（デフォルト："mongodb://localhost:27017"）
• MONGODB_DEFAULT_DB：デフォルトのデータベース名（任意）

接続プールの設定

• MONGODB_MIN_POOL_SIZE：接続プールの最小サイズ（デフォルト：0）
• MONGODB_MAX_POOL_SIZE：接続プールの最大サイズ（デフォルト：100）
• MONGODB_MAX_IDLE_TIME_MS：最大アイドル時間（ミリ秒、デフォルト：30000）

タイムアウトの設定

• MONGODB_SERVER_SELECTION_TIMEOUT_MS：サーバー選択のタイムアウト（デフォルト：30000）
• MONGODB_SOCKET_TIMEOUT_MS：ソケットのタイムアウト（デフォルト：0 - タイムアウトなし）
• MONGODB_CONNECT_TIMEOUT_MS：接続のタイムアウト（デフォルト：20000）

セキュリティ設定

• MONGODB_TLS_ENABLED：TLS 接続を有効化（デフォルト：false）
• MONGODB_AUTH_SOURCE：認証ソース（デフォルト：admin）
• MONGODB_AUTH_MECHANISM：認証メカニズム（SCRAM-SHA-1、SCRAM-SHA-256 など）

パフォーマンス設定

• MONGODB_READ_PREFERENCE：読み取り設定（デフォルト：primary）
• MONGODB_WRITE_CONCERN_W：書き込み確認レベル（デフォルト：1）
• MONGODB_READ_CONCERN_LEVEL：読み取り確認レベル（デフォルト：local）

ログ設定

• LOG_LEVEL：ログレベル（デフォルト："INFO"）
  • 使用可能な値：DEBUG、INFO、WARNING、ERROR、CRITICAL
• LOG_MAX_FILE_SIZE：ログファイルの最大サイズ（バイト単位、デフォルト：10MB）
• LOG_BACKUP_COUNT：バックアップログファイルの数（デフォルト：5）

機能フラグ

• ENABLE_DANGEROUS_OPERATIONS：危険を伴う可能性のある操作を有効にします（デフォルト：false）
• ENABLE_ADMIN_OPERATIONS：管理操作を有効にします（デフォルト：true）
• ENABLE_INDEX_OPERATIONS：インデックス操作を有効にします（デフォルト：true）

開発ガイド

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

git clone https://github.com/441126098/mongo-mcp.git
cd mongo-mcp

2. 開発用の依存関係をインストールします

# Using uv (recommended)
uv sync

# Or using pip
pip install -e ".[dev]"

3. テストを実行します

uv run pytest tests/ -v

4. コード構成

• src/mongo_mcp/server.py：MCP サーバーの実装
• src/mongo_mcp/db.py：MongoDB のコア操作の実装
• src/mongo_mcp/config.py：設定管理
• src/mongo_mcp/tools/：MCP ツールの実装
  • database_tools.py：データベースとコレクションの管理
  • document_tools.py：ドキュメントの CRUD 操作
  • index_tools.py：インデックス管理
  • aggregation_tools.py：集計操作
  • admin_tools.py：管理および監視ツール
• src/mongo_mcp/utils/：ユーティリティモジュール
• tests/：テストケース

テスト

このプロジェクトには、包括的なテストが含まれています。

• すべてのツールモジュールのユニットテスト
• MongoDB との統合テスト
• コンポーネントを分離してテストするためのモックテスト

テストスイートを実行します。

# Run all tests
uv run pytest

# Run with verbose output
uv run pytest -v

# Run specific test file
uv run pytest tests/test_tools.py

ログ

ログファイルは、デフォルトで logs ディレクトリに保存されます。ログシステムは次の機能をサポートしています。

• 設定可能なログレベル
• サイズに基づくファイルローテーション
• UTF-8 エンコーディングのサポート
• 関数名と行番号を含む構造化ログ

ライセンス

MIT

コントリビューション

Issue や Pull Request によるコントリビューションを歓迎します。PR を送信する前に、次の点を確認してください。

1. すべてのテストが成功すること（uv run pytest）
2. 適切なテストケースが追加されていること
3. ドキュメントが更新されていること
4. コードが既存のスタイルに従っていること