Skip to main content
Glama
any-db-mcp

any-db-mcp

by Yukuiii

any-db-mcp

English | 简体中文

让大模型通过 MCP (Model Context Protocol) 安全地操作数据库。支持 MySQL / MariaDB / PostgreSQL / SQLite / Microsoft SQL Server / Oracle。

npm version

特性

  • 统一适配:MySQL / MariaDB / PostgreSQL / SQLite / MSSQL / Oracle 共用同一套工具接口

  • 双传输模式:stdio 本地子进程 + Streamable HTTP 远程,后者带 stateful session 与可选 Bearer Token 鉴权

  • MCP Resources 暴露 schema:db://tables、db://table/{name} 与 db://table/{schema}/{name} 让客户端主动消化库结构,大幅减少每次对话重复 describe 的 token 开销

  • 三档权限模式:readonly / readwrite / full,启动时由环境变量决定,运行时不可篡改(5 层防 LLM 提权设计)

  • 事务支持:单工具批量提交,任一失败自动回滚

  • 连接弹性:TCP keepalive + 连接丢失自动重建并重试 + 健康检查工具

  • 一次调研到位:describe_table 一次返回列定义、索引、行数估算、数据采样,减少 LLM 来回试探

  • 响应耗时透明:所有 SQL 类工具返回 elapsedMs,便于 LLM 感知性能并调整策略

  • 统一 JSON 响应:所有工具返回结构化 JSON,便于 LLM 解析

  • 零部署:通过 npx 一行命令即可在任意 MCP 客户端中使用

Related MCP server: MCP SQL Server

工具一览

Tool

说明

受权限模式约束

connect

动态连接数据库,返回当前数据库的表信息列表与权限模式

否

disconnect

主动断开连接并释放连接池(幂等)

否

connection_status

查看当前连接状态、ping 健康度、表信息列表与权限模式

否

query

执行只读查询(SELECT / SHOW / DESCRIBE),响应最多返回前 1000 行

否

execute

执行单条写操作(DML,或 full 模式下 DDL)

✓

transaction

在事务中顺序执行多条 SQL,任一失败回滚

✓

list_tables

列出当前连接数据库的所有表名与表注释

否

describe_table

一次返回指定表的列定义、索引、估算行数与数据采样

否

search_schema

按关键词搜索表名、列名和字段类型

否

explain

获取 SQL 执行计划(不实际执行原 SQL),辅助优化

否

权限模式(PERMISSION_MODE)

Mode

query

execute / transaction

DDL

适用场景

readonly

✓

✗

✗

生产环境查询、数据探索

readwrite ⭐默认

✓

✓ DML(INSERT/UPDATE/DELETE)

✗

常规业务操作

full

✓

✓ DML + DDL

✓

迁移、初始化、Schema 演进

安全保证:PERMISSION_MODE 只能在 server 启动时通过环境变量设定。AppConfig 在加载后被 Object.freeze 深冻结,且任何工具的 inputSchema 都不暴露权限相关参数,杜绝 LLM 通过"重连提权"等手段绕过限制。

快速开始

通过 npx 使用(推荐)

在 MCP 客户端配置中添加:

{
  "mcpServers": {
    "any-db-mcp": {
      "command": "npx",
      "args": ["-y", "@sakura0v0/any-db-mcp"],
      "env": {
        "PERMISSION_MODE": "readwrite",
        "DB_TYPE": "mysql",
        "DB_HOST": "localhost",
        "DB_PORT": "3306",
        "DB_USER": "root",
        "DB_PASSWORD": "your_password",
        "DB_NAME": "your_database"
      }
    }
  }
}

本地源码运行

npm install
npm run build
node dist/index.js

对应 MCP 客户端配置:

{
  "mcpServers": {
    "any-db-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/any-db-mcp/dist/index.js"],
      "env": {
        "PERMISSION_MODE": "readwrite"
      }
    }
  }
}

环境变量

变量

说明

默认值

PERMISSION_MODE

权限模式:readonly / readwrite / full

readwrite

DB_TYPE

数据库类型:mysql / mariadb / postgresql / sqlite / mssql / oracle

mysql

DB_HOST

数据库主机

localhost

DB_PORT

数据库端口

3306(MySQL/MariaDB)/ 5432(PG)/ 1433(MSSQL)/ 1521(Oracle)

DB_USER

数据库用户名

root

DB_PASSWORD

数据库密码

(空)

DB_NAME

默认数据库

(空)

DB_SCHEMA

仅 PostgreSQL/MSSQL/Oracle:schema 名称;空值表示所有非系统 schema

(空)

DB_FILEPATH

SQLite 数据库文件路径

(空)

DB_ENCRYPT

仅 MSSQL:是否启用 TLS 加密

true

DB_TRUST_SERVER_CERTIFICATE

仅 MSSQL:是否信任自签证书

false

QUERY_TIMEOUT_MS

query 工具响应超时时间(ms)

30000

MCP_TRANSPORT

传输方式:stdio(默认) / http

stdio

MCP_HTTP_HOST

仅 http:监听主机,公网暴露请显式设 0.0.0.0 并配 token

127.0.0.1

MCP_HTTP_PORT

仅 http:监听端口

3000

MCP_HTTP_PATH

仅 http:MCP endpoint 路径

/mcp

MCP_AUTH_TOKEN

仅 http:可选 Bearer Token,设置后所有请求需带 Authorization: Bearer <token>

(空,不鉴权)

不配置 DB_* 时,Server 启动后不自动连接,需 LLM 主动调用 connect 工具。

数据库连接示例

LLM 调用 connect 工具时的入参示例:

MySQL

{
  "type": "mysql",
  "host": "localhost",
  "port": 3306,
  "user": "root",
  "password": "xxx",
  "database": "mydb"
}

MariaDB

{
  "type": "mariadb",
  "host": "localhost",
  "port": 3306,
  "user": "root",
  "password": "xxx",
  "database": "mydb"
}

PostgreSQL

{
  "type": "postgresql",
  "host": "localhost",
  "port": 5432,
  "user": "postgres",
  "password": "xxx",
  "database": "mydb",
  "schema": "billing"
}

SQLite

{
  "type": "sqlite",
  "filepath": "/path/to/database.db"
}

Microsoft SQL Server

{
  "type": "mssql",
  "host": "localhost",
  "port": 1433,
  "user": "sa",
  "password": "xxx",
  "database": "mydb",
  "schema": "sales",
  "encrypt": true,
  "trustServerCertificate": false
}

Oracle

{
  "type": "oracle",
  "host": "localhost",
  "port": 1521,
  "user": "app",
  "password": "xxx",
  "database": "FREEPDB1",
  "schema": "BILLING"
}

Oracle 使用 oracledb Thin mode;database 参数可填写 service name,也可填写完整 TNS connect string。

协议兼容数据库可直接复用现有适配器:

  • TiDB / OceanBase 等 MySQL 协议兼容数据库 → 选 type: mysql

  • CockroachDB / YugabyteDB 等 PG 协议兼容数据库 → 选 type: postgresql

传输方式 (Transport)

支持两种 transport,通过 MCP_TRANSPORT 切换。

stdio (默认)

最常见的本地集成方式,client 以子进程方式启动 server,通过标准输入输出通信。无需端口/网络,Claude Code、Cursor 等 IDE 默认走这条路径。

Streamable HTTP

按 MCP spec 2025-03-26 实现:POST /mcp 接收 JSON-RPC,响应可为 JSON 或 SSE 流;GET /mcp 用于建立长连接接收 server-initiated 消息;DELETE /mcp 关闭 session。每个 session 由服务端生成 Mcp-Session-Id 头并返回,客户端后续请求需带回。

# 本地开发:监听 127.0.0.1,无鉴权
MCP_TRANSPORT=http npx @sakura0v0/any-db-mcp

# 远程访问:绑 0.0.0.0 + Bearer Token + 反向代理 TLS
MCP_TRANSPORT=http \
MCP_HTTP_HOST=0.0.0.0 \
MCP_HTTP_PORT=3000 \
MCP_AUTH_TOKEN="$(openssl rand -hex 32)" \
npx @sakura0v0/any-db-mcp

安全约定:

  • 默认 MCP_HTTP_HOST=127.0.0.1,只接受本机回环。生产远程访问务必同时设置 MCP_AUTH_TOKEN 并通过反向代理(nginx / caddy)套 TLS。

  • 设置 MCP_AUTH_TOKEN 后所有请求需带 Authorization: Bearer <token>,使用常数时间比较抵御计时攻击。

  • HTTP 请求 body 上限 1 MB,防止简单 DoS。

  • 多 session 共享 db 单例数据库连接池:适合"个人远程访问",多用户场景应每 client 部署独立 server。

响应格式

所有工具返回统一的 JSON 结构。

成功响应:

{
  "success": true,
  "rowCount": 2,
  "limit": 1000,
  "truncated": false,
  "timeoutMs": 30000,
  "rows": [
    { "id": 1, "name": "Alice" },
    { "id": 2, "name": "Bob" }
  ],
  "elapsedMs": 3
}

失败响应(MCP 协议层会同时设置 isError: true):

{
  "success": false,
  "error": "当前权限模式为 readonly,禁止任何写操作。"
}

表信息列表响应

list_tables、connect 和已连接状态下的 connection_status 都会返回 tableCount 与 tables。tables 是结构化表信息数组,不是字符串数组;PostgreSQL/MSSQL/Oracle 会带 schema:

{
  "success": true,
  "tableCount": 2,
  "tables": [
    { "schema": "public", "name": "users", "comment": "系统用户" },
    { "schema": "billing", "name": "orders", "comment": null }
  ],
  "elapsedMs": 4
}

schema 在 MySQL/SQLite 中为 null;comment 来自数据库原生表注释,无注释或 SQLite 这类无原生表注释的数据库返回 null。

search_schema 快速定位

search_schema 可按关键词搜索当前库的表名、列名和字段类型,适合大库中先定位相关表字段再调用 describe_table。响应最多返回前 50 个命中项,并带 failedTables 说明个别表结构读取失败的情况。

{
  "keyword": "email"
}

describe_table 增强响应

调用 describe_table 时可传入 schema 和 sampleLimit(默认 3,0 表示不采样,最大 20)。响应一次性返回结构、索引、行数估算与采样数据:

{
  "success": true,
  "schema": "public",
  "table": "users",
  "columns": [
    { "name": "id", "type": "bigint", "nullable": false, "key": "PRI", "extra": "auto_increment", "defaultValue": null, "comment": "用户 ID" },
    { "name": "email", "type": "varchar(120)", "nullable": false, "key": "UNI", "extra": "", "defaultValue": null, "comment": "邮箱地址" }
  ],
  "indexes": [
    { "name": "PRIMARY", "columns": ["id"], "unique": true },
    { "name": "uk_email", "columns": ["email"], "unique": true }
  ],
  "rowCount": 12453,
  "rowCountIsEstimate": true,
  "sampleCount": 3,
  "sample": [
    { "id": 1, "email": "alice@example.com" },
    { "id": 2, "email": "bob@example.com" },
    { "id": 3, "email": "carol@example.com" }
  ],
  "elapsedMs": 12
}

行数估算策略:

数据库

数据源

rowCountIsEstimate

备注

MySQL/MariaDB

information_schema.TABLES.TABLE_ROWS

true

InnoDB 估算,避免 COUNT(*) 全表扫描

PostgreSQL

pg_class.reltuples

true

依赖 ANALYZE,从未分析时为 null

MSSQL

sys.partitions

true

元数据估算,避免 COUNT(*) 全表扫描

Oracle

ALL_TABLES.NUM_ROWS

true

依赖统计信息,未收集时为 null

SQLite

SELECT COUNT(*)

false

本地文件,精确值

MCP Resources

除工具外,server 还暴露三个 MCP Resource,让客户端可以主动订阅库结构(配合 notifications/resources/list_changed,连接切换时自动刷新):

URI

类型

说明

db://tables

静态

当前库的所有表名 + 表注释 + 估算行数,JSON 格式,适合 LLM 一次摸清规模量级

db://table/{name}

动态模板

单表的列定义与索引,每张表自动一个 URI(由 server 根据当前库动态生成)

db://table/{schema}/{name}

动态模板

PostgreSQL/MSSQL/Oracle 跨 schema 精确定位单表结构

connect / disconnect 成功后会发送 notifications/resources/list_changed, 支持订阅的客户端会自动刷新可用资源列表。未连接时读 db://tables 返回 connected: false 的友好提示,读不存在的表返回 error 字段。

db://tables 返回示例:

{
  "connected": true,
  "databaseType": "postgresql",
  "tableCount": 2,
  "tables": [
    {
      "table": "users",
      "schema": "public",
      "comment": "系统用户",
      "rowCount": 12453,
      "rowCountIsEstimate": true
    },
    {
      "table": "orders",
      "schema": "billing",
      "comment": null,
      "rowCount": 98210,
      "rowCountIsEstimate": true
    }
  ]
}

与 list_tables / describe_table 工具的区别:Resources 是"声明式订阅",由客户端缓存并复用, 适合放进每次对话的上下文;Tools 是"命令式调用",适合需要最新数据(如刚做完写入)或需要采样数据时。

事务示例

LLM 调用 transaction 工具:

{
  "sqls": [
    "UPDATE accounts SET balance = balance - 100 WHERE user_id = 1",
    "UPDATE accounts SET balance = balance + 100 WHERE user_id = 2"
  ]
}

任一语句失败,事务自动回滚,所有改动撤销。

架构

src/
├── index.ts              入口:加载配置 → 注册工具 → 可选自动连接 → 按 transport 启动
├── transport.ts          stdio + Streamable HTTP 启动器(stateful session + Bearer)
├── config.ts             AppConfig 与 PermissionMode(启动后冻结,运行时不可改)
├── db.ts                 DatabaseManager 单例,持有当前 Adapter
├── adapters/
│   ├── types.ts          DatabaseAdapter 统一接口
│   ├── mysql.ts          mysql2/promise 连接池实现(MySQL/MariaDB)
│   ├── postgresql.ts     pg 连接池实现
│   ├── sqlite.ts         better-sqlite3 实现
│   ├── mssql.ts          mssql 连接池实现(SHOWPLAN_XML via transaction)
│   └── oracle.ts         oracledb Thin mode 连接池实现
└── tools/
    ├── index.ts          所有 Tools 注册入口
    ├── connect.ts        connect 工具
    ├── disconnect.ts     disconnect 工具
    ├── connection-status.ts connection_status 工具
    ├── query.ts          query 工具
    ├── execute.ts        execute 工具
    ├── transaction.ts    transaction 工具
    ├── list-tables.ts    list_tables 工具
    ├── describe-table.ts describe_table 工具
    ├── search-schema.ts  search_schema 工具
    ├── explain.ts        explain 工具
    ├── resources.ts      MCP Resources(db://tables + db://table/{name} + db://table/{schema}/{name})
    ├── permission.ts     权限检查 helper
    ├── response.ts       统一响应工厂 ok() / fail()
    └── sql-patterns.ts   SQL 类型正则 + 多语句拦截

License

MIT

Available Tools

10 tools
connectA

连接到数据库。支持 MySQL、MariaDB、PostgreSQL、SQLite、MSSQL、Oracle。传入连接参数后会建立新连接,之前的连接会被自动关闭。SQLite 只需要传 filepath 参数;PostgreSQL/MSSQL/Oracle 可通过 schema 指定命名空间,不传则列出所有非系统 schema;Oracle 的 database 参数表示 service name 或 TNS connect string;MSSQL 在 SQL Server 2019+ 默认要求加密,自签证书环境需将 trustServerCertificate 设为 true。连接成功后返回当前数据库的表信息列表与当前权限模式(权限模式仅由 server 启动配置决定,无法通过此工具修改)。

Inputs: type (required), host, port, user, +6 more.

connection_statusA

查看当前数据库连接的状态,返回是否已连接、数据库类型、ping 健康度(实测耗时)、表信息列表以及权限模式。LLM 在长时间未操作后或捕获到执行失败时可调用此工具确认连接可用性。

Inputs: no named parameters.

describe_tableA

查看指定表的详细信息,一次返回:列定义/索引/外键/估算行数/数据采样。PostgreSQL/MSSQL/Oracle 跨 schema 同名表时应传 schema 精确定位。LLM 在写 SQL 前调用此工具可同时拿到字段结构、关联关系、表大小量级、字段真实取值示例,大幅减少猜测。

Inputs: table (required), schema, sampleLimit.

disconnectA

主动断开当前数据库连接并释放连接池。断开后再次执行 query / execute 等操作前需调用 connect 工具重新连接。未连接时调用也安全(幂等)。

Inputs: no named parameters.

executeA

执行单条写操作。在 readwrite 模式下仅支持 DML(INSERT / UPDATE / DELETE);在 full 模式下额外支持 DDL(DROP / TRUNCATE / ALTER / CREATE / GRANT / REVOKE);readonly 模式禁用此工具。

Inputs: sql (required).

explainA

获取 SQL 的执行计划,辅助分析查询性能与优化。所有权限模式下均可调用(EXPLAIN 不实际执行原 SQL)。仅支持 SELECT / INSERT / UPDATE / DELETE / WITH 开头的语句;无需自带 EXPLAIN 前缀,适配器内部统一拼接。

Inputs: sql (required).

list_tablesA

列出当前连接数据库的所有表名与表注释。tables 字段为包含 schema/name/comment 的结构化列表。PostgreSQL/MSSQL/Oracle 未配置 schema 时返回所有非系统 schema 的表,已配置 schema 时只返回该 schema 的表。

Inputs: no named parameters.

queryA

执行只读 SQL 查询(SELECT / SHOW / DESCRIBE)。响应最多返回前 1000 行,并通过 limit 字段告知本次返回上限;超过 QUERY_TIMEOUT_MS 会失败。执行计划请使用 explain 工具。

Inputs: sql (required).

search_schemaB

按关键词搜索当前数据库 schema,匹配表名、列名和字段类型。适合在大库中快速定位相关表或字段,响应最多返回前 50 个命中项。

Inputs: keyword (required).

transactionA

在数据库事务中按顺序执行一组 SQL。任一语句失败则整体回滚;全部成功才提交。权限规则与 execute 一致:readonly 禁用;readwrite 仅 DML;full 支持 DML + DDL。常用于多步写操作的原子性保证(如转账、订单创建)。

Inputs: sqls (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.1/5.0

    Scored across 10 tools

    Disambiguation5/5

    每个工具都有清晰独特的用途:connect/disconnect/connection_status 处理连接管理,query/execute/transaction 处理 SQL 执行且界限分明(只读 vs 单条写 vs 批量事务),list_tables/describe_table/search_schema 处理 schema 探索,explain 处理执行计划。描述明确说明了彼此的区别与适用场景。

    Naming Consistency4/5

    大部分工具采用一致的 verb_noun 或名词模式(list_tables, describe_table, search_schema, connection_status),但 connect, disconnect, query, execute, explain, transaction 为单个动词/名词,虽常见但与前者混合。整体仍可读且惯例常见,属轻微不一致。

    Tool Count5/5

    10 个工具覆盖连接生命周期、SQL 执行、schema 发现与性能分析,规模适中,每个工具都有明确职责,无冗余或缺失感。

    Completeness5/5

    覆盖了数据库交互的完整生命周期:连接管理(connect/disconnect/status)、只读查询(query)、写操作(execute)、事务(transaction)、schema 探索(list_tables/describe_table/search_schema)及执行计划(explain),无明显缺口。

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      A lightweight MySQL MCP server that enables LLMs to interact with databases through tools for schema inspection and query execution. It features LLM-friendly formatting, SSL support, and a secure read-only mode with query timeout protections.
      7
      64 npm
      MIT
    • F
      license
      A
      quality
      D
      maintenance
      An MCP server that connects LLMs to SQL databases for development assistance, enabling query execution, schema exploration, and data manipulation while providing safety controls against destructive operations.
      5
      -
    • -
      license
      Not graded
      quality
      Not graded
      maintenance
      A multi-database MCP tool that enables LLM agents to securely query and write to databases via local stdio, supporting MySQL, Oracle, PostgreSQL, DM, SQLite and more.
      1
      -
    • A
      license
      Not graded
      quality
      C
      maintenance
      A multi-database MCP server that enables LLM agents to safely access MySQL, Oracle, DM, PostgreSQL, and SQLite databases with security features like whitelist, row count pre-check, and audit logging.
      3
      MIT