Sqldb MCP Server

sqldb-mcp服务器

A. 只读 模型上下文协议（MCP） 向LLM公开SQL数据库访问权限的服务器。

特性

• 多数据库 –支持 MSSQL, PostgreSQL，以及 MySQL
• 只读 –仅限 SELECT 允许使用语句（通过AST级SQL解析，使用每种DB类型的正确方言强制执行）
• LLM已优化 –结果使用紧凑的列格式（列列表+值行）来减少令牌使用
• 分页 – skip / take 参数自动上限为100行
• 总计数已知 –每个查询结果包括 meta.totalCount 因此LLM知道存在多少行
• 缓存 –查询/模式结果使用可配置的TTL缓存
• 文件导出 –将查询结果流式传输到CSV或JSON文件，没有行数限制
• 五个MCP工具: query, listTables, describeTable, explainQuery, exportQuery

安装

来自npm（推荐）

# Install globally
npm install -g @akrym1582/sqldb-mcp-server

# Or run directly with npx (no install needed)
npx @akrym1582/sqldb-mcp-server

来源

git clone https://github.com/akrym1582/sqldb-mcp-server.git
cd sqldb-mcp-server
npm install
npm run build

快速开始

# 1. Install globally
npm install -g @akrym1582/sqldb-mcp-server

# 2. Configure environment variables (see below)
export DB_TYPE=postgresql
export DB_HOST=localhost
export DB_USER=myuser
export DB_PASSWORD=mypassword
export DB_NAME=mydb

# 3. Run
sqldb-mcp-server

或者在MCP客户端配置中使用（例如Claude Desktop claude_desktop_config.json):

{
  "mcpServers": {
    "sqldb": {
      "command": "npx",
      "args": ["-y", "@akrym1582/sqldb-mcp-server"],
      "env": {
        "DB_TYPE": "postgresql",
        "DB_HOST": "localhost",
        "DB_PORT": "5432",
        "DB_USER": "myuser",
        "DB_PASSWORD": "mypassword",
        "DB_NAME": "mydb"
      }
    }
  }
}

环境变量

按DB类型列出的默认端口

MCP工具

query

执行a SELECT SQL语句。

{
  "sql": "SELECT id, name FROM users WHERE active = 1",
  "skip": 0,
  "take": 10
}

响应格式（紧凑/令牌高效）：

{
  "meta": { "totalCount": 42, "returnedCount": 10, "skip": 0, "take": 10 },
  "columns": ["id", "name"],
  "rows": [[1, "Alice"], [2, "Bob"], ...]
}

listTables

列出数据库中的所有基表。

[{ "schema": "dbo", "name": "users" }, ...]

describeTable

描述表的列、索引、外键、检查约束和大小统计信息。

{ "table": "dbo.users" }

explainQuery

返回SELECT查询的估计执行计划，而不执行它。

{ "sql": "SELECT * FROM orders WHERE status = 'open'" }

exportQuery

将SELECT查询结果流式传输到文件。专为大型数据集设计——没有行数限制，结果使用Node.js流直接写入磁盘。

{
  "sql": "SELECT * FROM large_table",
  "filepath": "/tmp/export.csv",
  "format": "csv",
  "options": { "delimiter": ",", "bom": false }
}

format 默认为 "csv" 如果省略。 "json" 也得到了支持。

CSV选项 （全部可选）：

JSON选项 （全部可选）：

响应格式：

{
  "filepath": "/tmp/export.csv",
  "format": "csv",
  "rowCount": 50000
}

该工具使用一个单独的、寿命更长的连接池，其 requestTimeout 由控制 EXPORT_QUERY_TIMEOUT （默认300 000毫秒=5分钟）。对于非常大的出口，增加这一价值。

发展

# Clone the repository
git clone https://github.com/akrym1582/sqldb-mcp-server.git
cd sqldb-mcp-server

# Install dependencies
npm install

# Configure environment
cp .env.example .env
# Edit .env with your DB credentials

# Run in dev mode (no compile step)
npm run dev

# Or build and run
npm run build
npm start

# Run unit tests
npm test

项目结构

src/
  mcp/
    server.ts           # MCP server entry point
    tools/
      query.ts          # query tool
      listTables.ts     # listTables tool
      describeTable.ts  # describeTable tool
      explainQuery.ts   # explainQuery tool
      exportQuery.ts    # exportQuery tool (streaming file export)
  db/
    index.ts            # DB adapter factory (selects adapter from DB_TYPE)
    types.ts            # DB interfaces (including queryStream)
    adapters/
      mssql.ts          # Microsoft SQL Server implementation
      postgresql.ts     # PostgreSQL implementation (pg + pg-cursor)
      mysql.ts          # MySQL implementation (mysql2)
  utils/
    row-result.ts       # Compact columnar result format
    sanitize.ts         # AST-based SQL read-only validation (dialect-aware)
    pagination.ts       # skip/take normalisation
    cache.ts            # TTL in-memory cache
    export-writer.ts    # Streaming CSV / JSON file writer
  __tests__/            # Unit tests