Skip to main content
Glama
deenesjakoruzh
aminyx

mcp-devdb

by aminyx
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

mcp-devdb

CI

面向本地开发数据库的安全、只读 MCP 服务器。编码代理经常需要查看你的开发数据库——模式、示例数据、查询计划、表大小——但一个朴素的数据库连接器会赋予它们完整的写入权限。mcp-devdb 是受保护的替代方案：一个 Model Context Protocol 服务器，通过强化的只读 SQL 防护、列掩码、结果上限和每会话查询预算来暴露内省工具。

v1 中的后端：PostgreSQL（通过 postgres）和 SQLite（通过 better-sqlite3）。适配器接口与引擎无关，因此以后可以添加 MySQL。

快速开始

  1. 在服务器将要运行的位置旁边创建 mcp-devdb.json（参见 mcp-devdb.example.json）：

{
  "databases": {
    "app": { "url": "postgres://dev:dev@localhost:5432/app_development" },
    "cache": { "url": "sqlite:./data/cache.db" }
  }
}

  1. 运行它：

npx mcp-devdb --config ./mcp-devdb.json

服务器通过 stdio 使用 MCP 协议通信；将你的 MCP 客户端指向该命令。连接字符串仅存在于配置文件或环境变量中（"url": "env:MY_DB_URL"，或没有配置文件时的 MCP_DEVDB_URL 回退）——模型永远无法提供连接字符串。

Claude Code

claude mcp add devdb -- npx mcp-devdb --config /absolute/path/to/mcp-devdb.json

Claude Desktop（claude_desktop_config.json）

{
  "mcpServers": {
    "devdb": {
      "command": "npx",
      "args": ["mcp-devdb", "--config", "/absolute/path/to/mcp-devdb.json"]
    }
  }
}

Related MCP server: MCP PostgreSQL

工具

工具

输入

返回内容

list_tables

database?

模式、表、视图，附带行数估算和磁盘占用大小

describe_table

database?、table

列、类型、可空性、默认值、主键、外键、索引

sample_rows

database?、table、limit?（最大 50）

前 N 行；超过 200 字符的单元格被截断；敏感列被掩码为 ***

run_query

database?、sql

受防护的只读查询；行数上限（200）+ 字节上限（256 KiB）；消耗查询预算

explain_query

database?、sql

执行计划——PostgreSQL EXPLAIN (FORMAT JSON)，SQLite EXPLAIN QUERY PLAN；消耗查询预算

db_overview

database?

数据库名称、大小、表数量、最大的表、扩展（PG）

当只配置了一个数据库时，database 是可选的；配置了多个时，请指定你要用的那个。

配置

工作目录中的 mcp-devdb.json，或通过 --config 指定的任意路径：

{
  "databases": {
    "app": {
      "url": "postgres://dev:dev@localhost:5432/app_development",
      "allowTables": ["users", "orders", "public.events_*"],
      "denyTables": ["audit_log"]
    },
    "billing": { "url": "env:BILLING_DEV_DATABASE_URL" }
  },
  "maskPatterns": ["password", "secret", "token", "key", "hash", "ssn", "card"],
  "queryBudget": 100,
  "rowLimit": 200,
  "byteLimit": 262144,
  "statementTimeoutMs": 5000
}

  • allowTables / denyTables——不区分大小写的名称，支持 * 通配符；包含点的规则匹配 schema.table。拒绝优先；非空的允许列表是排他性的。

  • maskPatterns——针对列名匹配的不区分大小写的正则表达式。

  • CLI 标志：--config <path>、--no-mask（禁用列掩码）、--help、--version。

安全模型（摘要）

完整的威胁模型见 SECURITY.md。简而言之：

  • 只读防护：每个 run_query/explain_query 语句都会被分词（引号、E'...' 转义、注释、美元引用字符串），并且必须以 SELECT / WITH / EXPLAIN / SHOW / VALUES 开头；多语句输入和任何顶层写/DDL 关键字都会被拒绝——CTE 后跟 INSERT 会被捕获，而 SELECT 'DROP TABLE x' 不会被误报。

  • 引擎级强制：SQLite 文件以只读方式打开；PostgreSQL 会话以 default_transaction_read_only=on 运行，使用显式 BEGIN READ ONLY 事务，并设置语句超时。

  • 列掩码默认开启（使用 --no-mask 选择退出），结果上限，以及每会话查询预算（默认 100；耗尽时会提示你重启服务器）。

  • 凭据永远不会到达模型：连接字符串仅来自本地配置/环境变量，并且会从每条错误消息中清除。

冒烟测试

scripts/verify-stdio.mjs 构建一个临时 SQLite 数据库，启动 node dist/cli.js，并通过原始 JSON-RPC 在 stdio 上驱动一次真实的 MCP 握手。实际输出：

$ node scripts/verify-stdio.mjs
initialize -> mcp-devdb 0.1.0 (protocol 2025-06-18)
tools/list -> db_overview, describe_table, explain_query, list_tables, run_query, sample_rows
tools/call list_tables ->
{
  "database": "demo",
  "dialect": "sqlite",
  "tableCount": 2,
  "tables": [
    {
      "schema": null,
      "name": "orders",
      "type": "table",
      "rowEstimate": 3,
      "sizeBytes": 4096,
      "sizePretty": "4.0 KiB"
    },
    {
      "schema": null,
      "name": "users",
      "type": "table",
      "rowEstimate": 2,
      "sizeBytes": 4096,
      "sizePretty": "4.0 KiB"
    }
  ]
}
tools/call run_query "DROP TABLE users" -> isError=true
  Query rejected by read-only guard: Only read-only statements are allowed; the statement must start with one of: SELECT, WITH, EXPLAIN, SHOW, VALUES
SMOKE TEST PASSED

限制

  • 还没有 MySQL。 src/adapters/types.ts 中的 DbAdapter 接口是扩展点。

  • 仅限开发数据库。 防护会在 SQL 层面阻止写入，但 SELECT 仍然可能调用标记不当或具有副作用的扩展函数（例如 dblink 打开它自己的非只读连接）。对于开发数据库可以接受；切勿将其指向生产环境。参见 SECURITY.md。

  • 防护是保守的：未加引号的列如果名称类似被禁止的关键字（例如一个字面意义上名为 update 的列）会被拒绝——请给它们加引号（"update"）以继续。

  • SELECT ... FOR UPDATE 会被拒绝（它会获取行锁）。

  • SQLite 行数使用 COUNT(*)；在超大文件上 list_tables 可能会很慢。

开发

npm install
npm run lint && npm run typecheck && npm test && npm run build
node scripts/verify-stdio.mjs

许可证

MIT——版权所有（c）2026 Aminyx

This server cannot be deployed

Shareable, User-Owned Context BackendPeople, applications, and agents read, write, and coordinate together in one context lake. Reach it over MCP, a CLI, a Python SDK, or REST.fulcradynamics.comAd

Maintenance

ActivitySlowing
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • pg-mcp

    andre-c-andersen
    A
    license
    B
    quality
    D
    maintenance
    A lightweight Postgres MCP server for safe database exploration and query analysis, read-only by default, with multi-database support.
    4
    4
    MIT

  • MCP PostgreSQL

    cuevacelis
    A
    license
    Not graded
    quality
    D
    maintenance
    A read-only MCP server for PostgreSQL that enables safe database introspection and querying via natural language.
    436 npm
    MIT

  • MCP SQL Server

    alegonzjur
    A
    license
    Not graded
    quality
    D
    maintenance
    Read-only MCP server for SQL databases (SQLite/PostgreSQL) that enables listing tables, describing schemas, and executing SELECT queries with safety guardrails.
    MIT

  • slcg

    aadhyathmik
    A
    license
    Not graded
    quality
    D
    maintenance
    Provides a read-only PostgreSQL MCP server with schema introspection. Enforces least-privilege database roles to prevent any writes, even from malicious SQL.
    MIT