Db MCP

🚀 db-mcp

db-mcp 是一個 Model Context Protocol (MCP) 服務器，它能夠連接並查詢 MySQL、Redis 和 MongoDB 數據庫，為用戶提供了便捷的數據庫操作體驗。

🚀 快速開始

前置要求

• 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 文件

✨ 主要特性

• ✅ MySQL 支持：可連接、查詢並執行 SQL 語句。
• ✅ Redis 支持：支持鍵值操作、哈希操作以及模式匹配。
• ✅ MongoDB 支持：能夠進行文檔查詢、插入、更新和刪除操作。
• 🔒 安全模式：支持只讀模式、限制模式、完全開發模式三種安全級別。

📦 安裝指南

前置要求

• 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 文件

💻 使用示例

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 } }

📚 詳細文檔

使用方法

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

更友好的 API，自動構建 SQL，使用參數化查詢防止 SQL 注入。 參數：

• 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：獲取當前安全模式

🔧 技術細節

開發

# 安裝依賴
npm install

# 構建
npm run build

# 開發模式（使用 tsx）
npm run dev

# 監聽模式
npm run watch

📄 許可證

MIT

貢獻

歡迎提交 Issue 和 Pull Request！

使用效果截圖

Redis 查詢示例

MySQL 統計查詢示例

MongoDB 統計查詢示例