Db MCP

🚀 db-mcp

db-mcpは、MySQL、Redis、MongoDBデータベースに接続してクエリを実行するためのModel Context Protocol (MCP)サーバーです。このサーバーを使用することで、様々なデータベースを一元的に管理し、操作することができます。

📸 使用效果截图

Redis 查询示例

MySQL 统计查询示例

MongoDB 统计查询示例

✨ 主な機能

• ✅ MySQL サポート: 接続、クエリ実行、SQL文の実行が可能です。
• ✅ Redis サポート: キー値操作、ハッシュ操作、パターンマッチングがサポートされています。
• ✅ MongoDB サポート: ドキュメントのクエリ、挿入、更新、削除が可能です。
• 🔒 セキュリティモード: 読み取り専用モード、制限モード、完全開発モードの3つのセキュリティレベルをサポートしています。

📦 インストール

前提条件

• Node.js >= 18.0.0
• npm >= 9.0.0 または yarn >= 1.22.0

インストール手順

# リポジトリをクローン
git clone git@github_pig:wannanbigpig/db-mcp.git
cd db-mcp

# 依存関係をインストール
npm install

# プロジェクトをビルド
npm run build

インストールの確認

ビルドが完了したら、以下のコマンドを実行してインストールを確認できます。

# 開発モードで実行（テスト）
npm run dev

# またはビルド後のファイルを直接実行
node dist/index.js

「db-mcp サーバーが起動しました」というメッセージが表示されれば、インストールは成功です。

データベース接続の設定（オプション）

インストールが完了したら、データベース接続を設定することができます。

1. サンプル設定ファイルをコピーします。

cp config.json.example config.json

2. config.json を編集して、データベースの接続情報を入力します。

詳細な設定については、データベース接続設定のセクションを参照してください。

トラブルシューティング

インストールまたは実行中に問題が発生した場合は、以下の手順を試してみてください。

1. Node.js のバージョンを確認する

node --version  # 18.0.0 以上である必要があります

2. キャッシュをクリアして再インストールする

rm -rf node_modules package-lock.json
npm install
npm run build

3. ビルド出力を確認する

ls -la dist/  # コンパイルされた .js ファイルが表示されるはずです

💻 使用例

db-mcpは標準的なMCP (Model Context Protocol)サーバーであり、MCPをサポートする任意のクライアントで使用できます。以下に例を示します。

• Cursor - AIコードエディタ
• Claude Desktop - AnthropicのClaudeデスクトップアプリ
• その他のMCP対応クライアント

MCPサーバーの設定

MCPクライアントの設定ファイルにdb-mcpサーバーの設定を追加します。設定形式はクライアントによって異なります。

Cursorの設定例

Cursorの設定ファイル（通常は ~/.cursor/mcp.json またはCursor設定のMCP設定）に以下を追加します。

{
  "mcpServers": {
    "db-mcp": {
      "command": "node",
      "args": ["/path/to/db-mcp/dist/index.js"],
      "env": {
        "DB_MCP_SECURITY_MODE": "read_only",
        "DB_MCP_CONFIG_PATH": "/path/to/config.json"
      }
    }
  }
}

Claude Desktopの設定例

Claude Desktopの設定ファイル（通常は ~/Library/Application Support/Claude/claude_desktop_config.json）に以下を追加します。

{
  "mcpServers": {
    "db-mcp": {
      "command": "node",
      "args": ["/path/to/db-mcp/dist/index.js"],
      "env": {
        "DB_MCP_SECURITY_MODE": "read_only"
      }
    }
  }
}

注意: /path/to/db-mcp/dist/index.js を実際のインストールパスに置き換えてください。

データベース接続の事前設定

config.json または環境変数を使用して、データベース接続を事前に設定することができます。config.json.example を config.json にコピーして編集するだけです。

環境変数の例: MYSQL_HOST、MYSQL_USER、MYSQL_PASSWORD、REDIS_HOST、MONGODB_URL など。

セキュリティモード

DB_MCP_SECURITY_MODE 環境変数または set_security_mode ツールを使用して設定できます。

• read_only (デフォルト): クエリ操作のみ許可されます。
• restricted: クエリと一部の変更操作が許可され、危険な操作（DROP、TRUNCATE、ALTER TABLE など）は禁止されます。
• full_access: すべての操作が許可され、テーブル構造の変更も可能です。

開発モード

npm run dev

📚 ドキュメント

データベース接続設定

事前設定による接続（推奨）

config.json または環境変数を使用してデータベース接続を事前に設定すると、サーバー起動時に自動的に接続されます。

MySQLの設定例:

{
  "databases": {
    "mysql": {
      "host": "localhost",
      "port": 3306,
      "user": "root",
      "password": "your_password",
      "database": "mydb",
      "pool": { "min": 2, "max": 10, "idleTimeout": 60000 }
    }
  }
}

Redisの設定例:

{
  "databases": {
    "redis": {
      "host": "localhost",
      "port": 6379,
      "password": "your_password",
      "db": 0
    }
  }
}

MongoDBの設定例:

{
  "databases": {
    "mongodb": {
      "url": "mongodb://localhost:27017",
      "database": "mydb"
    }
  }
}

動的接続

*_connect ツールを使用して動的に接続し、*_disconnect ツールを使用して接続を切断することもできます。

利用可能なツール

MySQLツール

mysql_connect

MySQLデータベースに接続します（接続プールをサポート）。事前に設定された接続がある場合、このツールは再接続します。

パラメータ:

• host (必須): MySQLホストアドレス
• port (オプション): MySQLポート、デフォルトは3306
• user (必須): MySQLユーザー名
• password (必須): MySQLパスワード
• database (オプション): データベース名
• usePool (オプション): 接続プールを使用するかどうか、デフォルトは false
• pool (オプション): 接続プールの設定
  • min: 最小接続数、デフォルトは2
  • max: 最大接続数、デフォルトは10
  • idleTimeout: アイドルタイムアウト時間（ミリ秒）、デフォルトは60000

mysql_query

MySQL SQL文を実行します（すべてのSQL操作をサポート、テーブル構造の変更も含む）。

パラメータ:

• sql (必須): SQL文
• params (オプション): SQLパラメータの配列

例:

{ "sql": "SELECT * FROM users WHERE id = ?", "params": [1] }
{ "sql": "CREATE TABLE users (id INT PRIMARY KEY, name VARCHAR(100))" }
{ "sql": "ALTER TABLE users ADD COLUMN age INT" }

mysql_insert / mysql_update / mysql_delete

SQLを自動的に構築し、パラメータ化されたクエリを使用してSQLインジェクションを防止する、より使いやすいAPIです。

パラメータ:

• table (必須): テーブル名
• data (insert/update 必須): データオブジェクト
• where (update/delete 必須): WHERE条件オブジェクト

例:

{ "table": "users", "data": { "name": "John", "email": "john@example.com" } }
{ "table": "users", "data": { "name": "Jane" }, "where": { "id": 1 } }
{ "table": "users", "where": { "id": 1 } }

mysql_disconnect

MySQLデータベースの接続を切断します。

mysql_pool_status

MySQL接続プールの状態を取得します（接続プールを使用している場合のみ有効）。

パラメータ: なし

戻り値: 接続プールの状態情報（総接続数、アクティブ接続数、アイドル接続数）

Redisツール

• redis_connect: Redisに接続します（パラメータ: host, port, password, db, url）
• redis_get: キーの値を取得します（パラメータ: key）
• redis_set: キーと値を設定します（パラメータ: key, value, ttl）
• redis_keys: 一致するキーを検索します（パラメータ: pattern）
• redis_del: キーを削除します（パラメータ: key）
• redis_hget: ハッシュフィールドを取得します（パラメータ: key, field）
• redis_hgetall: すべてのハッシュフィールドを取得します（パラメータ: key）
• redis_disconnect: 接続を切断します

MongoDBツール

• mongodb_connect: MongoDBに接続します（パラメータ: url, database）
• mongodb_find: ドキュメントを検索します（パラメータ: collection, filter, limit, skip, sort）
• mongodb_find_one: 単一のドキュメントを検索します（パラメータ: collection, filter）
• mongodb_insert_one: 単一のドキュメントを挿入します（パラメータ: collection, document）
• mongodb_insert_many: 複数のドキュメントを挿入します（パラメータ: collection, documents）
• mongodb_update_one: ドキュメントを更新します（パラメータ: collection, filter, update）
• mongodb_delete_one: ドキュメントを削除します（パラメータ: collection, filter）
• mongodb_count: ドキュメントの数をカウントします（パラメータ: collection, filter）
• mongodb_list_collections: すべてのコレクションをリストします
• mongodb_disconnect: 接続を切断します

セキュリティ設定ツール

• set_security_mode: セキュリティモードを設定します（パラメータ: mode - read_only/restricted/full_access）
• get_security_mode: 現在のセキュリティモードを取得します

💻 使用例

MySQL

// 接続
{ "host": "localhost", "user": "root", "password": "pass", "database": "mydb" }

// クエリ
{ "sql": "SELECT * FROM users WHERE id = ?", "params": [1] }

// 挿入
{ "table": "users", "data": { "name": "John", "email": "john@example.com" } }

Redis

// 接続
{ "host": "localhost", "port": 6379, "db": 0 }

// 操作
{ "key": "user:1", "value": "John Doe", "ttl": 3600 }
{ "key": "user:1" }
{ "pattern": "user:*" }

MongoDB

// 接続
{ "url": "mongodb://localhost:27017", "database": "mydb" }

// 操作
{ "collection": "users", "filter": { "age": { "$gte": 18 } }, "limit": 10 }
{ "collection": "users", "document": { "name": "John", "age": 30 } }

🔧 開発

# 依存関係をインストール
npm install

# ビルド
npm run build

# 開発モード（tsxを使用）
npm run dev

# 監視モード
npm run watch

📄 ライセンス

MIT

貢献

IssueとPull Requestの投稿を歓迎します！