@firejeff01/dbcli-server

v2.0.0

Published

9 days ago

MCP Server for executing read-only database queries via CLI tools

0High
0Medium
0Low

firejeff01

mcp database cli sqlcmd mysql psql

DB CLI MCP Server

English README

一個 Model Context Protocol (MCP) 伺服器，提供統一、安全、AI 友善的介面，透過 CLI 工具跨多種資料庫執行唯讀查詢。

功能特色

多資料庫支援 — SQL Server、MySQL、MariaDB、PostgreSQL、Oracle
唯讀強制執行 — 嚴格的 SELECT-only 查詢驗證，採用 fail-closed 原則
零設定啟動 — 即使沒有設定檔或 CLI 工具，伺服器也能正常啟動
自動偵測 — 掃描專案檔案（.env、appsettings.json、docker-compose.yml 等）自動發現資料庫設定
暫時連線 — 僅存於記憶體中的臨時連線，不會寫入磁碟
CLI 工具指引 — 偵測缺失的 CLI 工具並提供安裝教學
AI 原生設計 — 透過 MCP 協定與各種 AI IDE 和 CLI 工具無縫整合

支援的資料庫

| 資料庫 | CLI 工具 | 預設連接埠 | |-------------|-----------|-----------| | SQL Server | sqlcmd | 1433 | | MySQL | mysql | 3306 | | MariaDB | mariadb | 3306 | | PostgreSQL | psql | 5432 | | Oracle | sqlplus | 1521 |

安裝方式

前置需求

Node.js 18 或更新版本
至少一個資料庫 CLI 工具已安裝（選用 — 伺服器在沒有 CLI 工具時也能運作）

透過 npm 安裝

npm install -g @firejeff01/dbcli-server

從原始碼安裝

git clone https://github.com/your-org/dbcli-mcp-server.git
cd dbcli-mcp-server
npm install
npm run build

快速開始

1. 啟動伺服器

# 透過 npx（無需安裝）
npx @firejeff01/dbcli-server --stdio

# 或者已全域安裝的情況
dbcli-mcp-server --stdio

2. 檢查系統狀態

使用 doctor 工具檢視 CLI 工具及設定狀態：

{
  "serverVersion": "2.0",
  "cliStatus": [
    { "dbType": "mssql", "cli": "sqlcmd", "installed": true, "version": "17.10" },
    { "dbType": "mysql", "cli": "mysql", "installed": false }
  ],
  "issues": ["mysql not installed"]
}

3. 執行查詢

// 輸入
{ "sql": "SELECT * FROM users LIMIT 10" }

// 輸出
{
  "success": true,
  "columns": ["id", "name", "email"],
  "rows": [
    { "id": "1", "name": "Alice", "email": "[email protected]" }
  ],
  "rowCount": 1,
  "truncated": false
}

AI IDE 與 CLI 工具整合

Claude Code

Claude Code 原生支援 MCP 伺服器。

設定方式

將伺服器加入 Claude Code 的 MCP 設定：

claude mcp add dbcli -- npx @firejeff01/dbcli-server --stdio

或手動編輯 ~/.claude/claude_desktop_config.json：

{
  "mcpServers": {
    "dbcli": {
      "command": "npx",
      "args": ["@firejeff01/dbcli-server", "--stdio"]
    }
  }
}

使用方式

設定完成後，直接在 Claude Code 中詢問：

> 查詢 users 資料表，顯示前 10 筆資料
> 檢查系統上安裝了哪些資料庫 CLI 工具
> 建立一個連接到本地 MySQL 資料庫的暫時連線
> 掃描這個專案中的資料庫設定

Codex CLI

Codex CLI 支援 MCP 協定整合。

設定方式

編輯 Codex CLI 設定檔 ~/.codex/config.json：

{
  "mcpServers": {
    "dbcli": {
      "command": "npx",
      "args": ["@firejeff01/dbcli-server", "--stdio"]
    }
  }
}

使用方式

codex "查詢本地 SQL Server 資料庫的 users 資料表"
codex "這個專案有哪些資料庫設定？"

Cursor

Cursor 支援 MCP 伺服器，用於 AI 輔助開發。

設定方式

開啟 Cursor 設定：Ctrl+Shift+J（Windows/Linux）或 Cmd+Shift+J（macOS）
導航到 MCP 區段
點擊 「Add new MCP server」
填入設定：

{
  "mcpServers": {
    "dbcli": {
      "command": "npx",
      "args": ["@firejeff01/dbcli-server", "--stdio"]
    }
  }
}

或手動編輯專案根目錄下的 .cursor/mcp.json：

{
  "mcpServers": {
    "dbcli": {
      "command": "npx",
      "args": ["@firejeff01/dbcli-server", "--stdio"]
    }
  }
}

使用方式

在 Cursor 的 AI 聊天或 Composer 中：

@dbcli 執行 SELECT * FROM products WHERE price > 100
@dbcli 顯示 orders 資料表的結構
@dbcli 建立暫時連線到 postgres://localhost:5432/mydb

VS Code (Copilot)

VS Code 搭配 GitHub Copilot 支援 MCP 伺服器（需安裝 Copilot Chat）。

設定方式

安裝 GitHub Copilot 和 GitHub Copilot Chat 擴充套件
開啟 VS Code 設定（Ctrl+,）
在設定中搜尋 mcp
編輯 settings.json 並加入：

{
  "github.copilot.chat.mcp.servers": {
    "dbcli": {
      "command": "npx",
      "args": ["@firejeff01/dbcli-server", "--stdio"]
    }
  }
}

或在專案中建立 .vscode/mcp.json：

{
  "servers": {
    "dbcli": {
      "command": "npx",
      "args": ["@firejeff01/dbcli-server", "--stdio"]
    }
  }
}

使用方式

在 Copilot Chat 面板中：

@dbcli 這個專案設定了哪些資料庫連線？
@dbcli 對我的資料庫設定進行健康檢查
@dbcli SELECT COUNT(*) FROM orders WHERE status = 'pending'

GitHub Copilot CLI

GitHub Copilot CLI 可以利用 MCP 伺服器。

設定方式

透過 ~/.config/github-copilot/config.json 設定：

{
  "mcpServers": {
    "dbcli": {
      "command": "npx",
      "args": ["@firejeff01/dbcli-server", "--stdio"]
    }
  }
}

使用方式

gh copilot explain "如何使用 dbcli MCP 伺服器查詢資料庫"

Visual Studio 2026

Visual Studio 2026 透過 AI 整合功能支援 MCP 伺服器。

設定方式

開啟工具 → 選項 → GitHub Copilot → MCP Servers
點擊 「新增伺服器」
設定：
- 名稱: dbcli
- 命令: npx
- 參數: @firejeff01/dbcli-server --stdio

或在方案根目錄建立 .vs/mcp.json：

{
  "servers": {
    "dbcli": {
      "command": "npx",
      "args": ["@firejeff01/dbcli-server", "--stdio"]
    }
  }
}

使用方式

在 Copilot Chat 視窗中：

@dbcli 查詢本月的客戶資料
@dbcli 檢查 sqlcmd 是否已安裝，如果沒有請顯示安裝指引

MCP Tools 參考

`doctor()`

回傳系統診斷資訊，包含伺服器版本、CLI 工具安裝狀態及偵測到的問題。

參數: 無

回應範例:

{
  "serverVersion": "2.0",
  "cliStatus": [
    { "dbType": "mssql", "cli": "sqlcmd", "installed": true, "version": "17.10", "path": "/usr/bin/sqlcmd" }
  ],
  "issues": []
}

`scanProjectDbConfigs()`

掃描當前專案目錄中常見設定檔的資料庫設定。

掃描檔案: .env、.env.*、appsettings.json、application.yml、application.properties、docker-compose.yml

參數: 無

回應範例:

[
  {
    "dbType": "mssql",
    "host": "localhost",
    "port": 1433,
    "database": "ExampleDB",
    "source": "appsettings.json"
  }
]

`initConfig()`

在 .mcp/dbcli.config.json 中建立或更新持久化設定 Profile。

參數:

| 參數名稱 | 型別 | 必填 | 說明 | |-----------------|--------|------|-------------------------------| | profileName | string | 是 | Profile 名稱（如 "dev"） | | dbType | string | 是 | 資料庫類型 | | host | string | 是 | 資料庫主機 | | database | string | 是 | 資料庫名稱 | | port | number | 否 | 連接埠 | | username | string | 否 | 使用者名稱 | | password | string | 否 | 密碼 | | timeoutSeconds | number | 否 | 查詢逾時秒數（預設：30） | | maxRows | number | 否 | 最大回傳筆數（預設：500） |

`setActiveProfile()`

切換作用中的設定 Profile。

參數:

| 參數名稱 | 型別 | 必填 | 說明 | |-------------- |--------|------|--------------------| | profileName | string | 是 | 要啟用的 Profile 名稱 |

`getInstallInstructions()`

回傳特定資料庫 CLI 工具的安裝指引（依作業系統區分）。

參數:

| 參數名稱 | 型別 | 必填 | 說明 | |---------|--------|------|-----------| | dbType | string | 是 | 資料庫類型 |

回應範例:

{
  "dbType": "mssql",
  "cli": "sqlcmd",
  "installed": false,
  "instructions": {
    "windows": "winget install Microsoft.SQLCMD",
    "linux": "sudo apt install mssql-tools",
    "macos": "brew install mssql-tools"
  }
}

`createTemporaryConnection()`

建立僅存於記憶體中的暫時資料庫連線，永遠不會寫入磁碟。

參數:

| 參數名稱 | 型別 | 必填 | 說明 | |-----------|--------|------|-------------| | dbType | string | 是 | 資料庫類型 | | host | string | 是 | 資料庫主機 | | database | string | 是 | 資料庫名稱 | | port | number | 否 | 連接埠 | | username | string | 否 | 使用者名稱 | | password | string | 否 | 密碼 |

回應範例:

{
  "id": "uuid-string",
  "type": "temporary",
  "dbType": "mssql",
  "cli": "sqlcmd",
  "connection": {
    "host": "localhost",
    "database": "TestDB",
    "password": "***"
  }
}

`runSelectQuery()`

透過對應的資料庫 CLI 工具執行唯讀 SQL 查詢。

參數:

| 參數名稱 | 型別 | 必填 | 說明 | |---------------|--------|------|------------------------------------------| | sql | string | 是 | SELECT SQL 查詢語句 | | connectionId | string | 否 | 暫時連線 ID（未指定時使用作用中的 Profile） |

允許的 SQL 類型:

SELECT ...
WITH ... SELECT ...（CTE 通用資料表運算式）
EXPLAIN SELECT ...

回應範例:

{
  "success": true,
  "columns": ["id", "name"],
  "rows": [{ "id": "1", "name": "Alice" }],
  "rowCount": 1,
  "truncated": false
}

連線模式

| 模式 | 說明 | 持久性 | |---------------|----------------------------------------|---------| | 專案偵測 | 自動從專案檔案偵測連線資訊 | 無 | | 設定 Profile | 儲存於 .mcp/dbcli.config.json | 磁碟 | | 暫時連線 | 僅存於執行期間，透過 createTemporaryConnection() 建立 | 僅記憶體 |

設定檔結構

{
  "version": 1,
  "activeProfile": "dev",
  "profiles": {
    "dev": {
      "dbType": "mssql",
      "cli": "sqlcmd",
      "connection": {
        "host": "localhost",
        "port": 1433,
        "database": "ExampleDb",
        "username": "app",
        "password": "${DB_PASSWORD}"
      },
      "limits": {
        "timeoutSeconds": 30,
        "maxRows": 500
      }
    }
  }
}

安全性

核心安全規則

SELECT-only 查詢 — 所有 DML/DDL 操作嚴格禁止
Fail-closed 驗證 — SQL 解析器無法判斷查詢類型時，一律拒絕
認證資訊不暴露 — 所有 API 回應中的密碼皆被遮蔽
結果筆數限制 — maxRows 防止過量資料擷取
查詢逾時控制 — timeoutSeconds 自動終止長時間執行的查詢
防止 Shell 注入 — CLI 執行使用 execFile（而非 exec），防止 Shell 注入攻擊
多語句拒絕 — 分號分隔的多語句查詢一律阻擋
暫時連線隔離 — 臨時連線永遠不會寫入磁碟

禁止的 SQL 操作

INSERT、UPDATE、DELETE、MERGE、CREATE、ALTER、DROP、TRUNCATE、EXEC、EXECUTE、CALL、GRANT、REVOKE、SELECT INTO

開發指南

# 安裝相依套件
npm install

# 編譯
npm run build

# 執行測試
npm test

# 以監看模式執行測試
npm run test:watch

專案結構

src/
├── index.ts                  # MCP Server 進入點 + Tool 定義
├── types.ts                  # 核心 TypeScript 型別
├── server/
│   └── ConnectionStore.ts    # 暫時連線記憶體儲存
├── validator/
│   └── SqlValidator.ts       # SQL 安全驗證
├── cli/
│   ├── CliManager.ts         # CLI 偵測 + 安裝指引
│   └── CliExecutor.ts        # 安全 CLI 執行
├── config/
│   └── ConfigManager.ts      # 設定檔管理
├── scanner/
│   └── ProjectScanner.ts     # 專案資料庫設定掃描
└── formatter/
    └── ResultFormatter.ts    # 查詢結果格式化

系統架構

AI 用戶端（Claude Code / Cursor / VS Code / Codex CLI / ...）
    │
    │  MCP 協定（JSON-RPC over stdio）
    ▼
┌──────────────────────────────┐
│       MCP Server Core        │
│  （Tool 路由 & 生命週期管理）  │
└──────────┬───────────────────┘
           │
     ┌─────┼─────┬──────────┬──────────┬──────────┐
     ▼     ▼     ▼          ▼          ▼          ▼
  專案     CLI   設定檔      SQL       CLI       結果
  掃描器   管理器 管理器    驗證器     執行器    格式化器

授權條款

MIT License。詳見 LICENSE。

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

DB CLI MCP Server

目錄

功能特色

支援的資料庫

安裝方式

前置需求

透過 npm 安裝

從原始碼安裝

快速開始

1. 啟動伺服器

2. 檢查系統狀態

3. 執行查詢

AI IDE 與 CLI 工具整合

Claude Code

設定方式

使用方式

Codex CLI

設定方式

使用方式

Cursor

設定方式

使用方式

VS Code (Copilot)

設定方式

使用方式

GitHub Copilot CLI

設定方式

使用方式

Visual Studio 2026

設定方式

使用方式

MCP Tools 參考

doctor()

scanProjectDbConfigs()

initConfig()

setActiveProfile()

getInstallInstructions()

createTemporaryConnection()

runSelectQuery()

連線模式

設定檔結構

安全性

核心安全規則

禁止的 SQL 操作

開發指南

專案結構

系統架構

授權條款

`doctor()`

`scanProjectDbConfigs()`

`initConfig()`

`setActiveProfile()`

`getInstallInstructions()`

`createTemporaryConnection()`

`runSelectQuery()`