mcp-database-server-v2

# mcp-server-db [](https://www.npmjs.com/package/mcp-server-db) [](https://github.com/Nam088/mcp-database-server/blob/main/LICENSE) [](https://nodejs.org) [](https://www.typescriptlang.org) **mcp-server-db** 是一个通用、生产级别的模型上下文协议（MCP）服务器，支持 AI 助手通过统一的 113+ 高性能工具与 **Postgres、Redis、Elasticsearch、MySQL、MongoDB 和 LDAP** 进行交互。 该服务器具有弹性，具备后台惰性连接管理、指数级重试、断路器模式、严格的只读安全强制和按需动态驱动程序加载等功能。 --- ## 为什么选择 mcp-server-db？ - **多数据库支持**：同时连接 Postgres、Redis、Elasticsearch（v7、v8 和 v9）、MySQL、MongoDB 和 LDAP 目录。 - **按需轻量驱动程序**：零冗余。驱动程序（`pg`、`ioredis`、`mongodb`、`mysql2`、`@elastic/elasticsearch`、`ldapts`）仅在初始化到该数据库引擎的连接时动态加载。 - **坚固的安全性**：独立的每个连接的只读模式，具有会话级别的强制执行，用于关系数据库和查询结果截断保护，以防止 LLM 上下文溢出。 - **容错架构**：服务器立即启动，而不管数据库可用性如何。失效或无法访问的数据库不会崩溃 MCP 进程或阻止其他连接。 - **多连接路由**：在同一会话中并行查询多个环境（例如，生产只读副本 + 本地缓存）。 --- ## 支持的数据库引擎 | 数据库引擎 | 默认驱动程序 | 支持版本 | 关键功能和防护措施 | | --- | --- | --- | --- | | **PostgreSQL** | `pg`（可选） | 10+ | 表/索引统计、健康诊断、会话级 `read_only`、语句超时 | | **Redis** | `ioredis`（可选） | 5+ | 键/字符串/哈希/集合/列表操作、自动 1000 项结果截断上限 | | **Elasticsearch** | `@elastic/elasticsearch` / `es7-client` | 7.x、8.x、9.x | 双 API 版本外观（v7 旧版和 v8/v9 现代版）、集群健康、查询 DSL | | **MySQL / MariaDB** | `mysql2`（可选） | 5.7+、8.0+ | DDL 提取（`SHOW CREATE`）、进程列表管理、索引和触发器、会话只读 | | **MongoDB** | `mongodb`（可选） | 4.4+ | 聚合管道、不同查询、索引管理、执行计划解释 | | **LDAP** | `ldapts`（可选） | v3 目录（OpenLDAP、AD 等） | 搜索/比较、添加/修改/删除条目、批量条目播种 | --- ## 快速入门 ### 1. 安装和可选驱动程序 全局安装（`npm install -g mcp-server-db`）或通过 `npx -y mcp-server-db` 运行，npm 会自动通过 `optionalDependencies` 包含所有支持的数据库驱动程序。 ```bash # 全局安装（包含所有驱动程序） npm install -g mcp-server-db # 本地项目安装 npm install mcp-server-db ``` 如果您使用 `--no-optional` 本地安装 `mcp-server-db` 以保持 `node_modules` 轻量，您可以仅安装您需要的特定驱动程序： ```bash # PostgreSQL npm install pg # Redis npm install ioredis # Elasticsearch npm install @elastic/elasticsearch # 用于 v8 和 v9 npm install es7-client # 用于 v7 旧版 # MySQL / MariaDB npm install mysql2 # MongoDB npm install mongodb # LDAP npm install ldapts ``` ### 2. 通过 NPX 零安装执行 将 `mcp-server-db` 直接添加到您的 MCP 客户端配置文件中（例如 Claude Desktop、Claude Code、Gemini CLI、Cursor）： ```json { "mcpServers": { "mcp-server-db": { "type": "stdio", "command": "npx", "args": ["-y", "mcp-server-db"], "env": { "POSTGRES_URL": "postgresql://user:password@localhost:5432/mydb", "REDIS_URL": "redis://localhost:6379", "MONGODB_URL": "mongodb://localhost:27017", "LDAP_URL": "ldap://localhost:389", "LDAP_BIND_DN": "cn=admin,dc=example,dc=com", "LDAP_BIND_PASSWORD": "admin-password" } } } } ``` ### 3. 使用环境变量快速设置 在 `env` 中定义连接字符串以立即启动而无需配置文件： ```bash POSTGRES_URL=postgresql://user:password@localhost:5432/mydb REDIS_URL=redis://localhost:6379 ELASTICSEARCH_URL=http://localhost:9200 MYSQL_URL=mysql://user:password@localhost:3306/mydb MONGODB_URL=mongodb://localhost:27017 LDAP_URL=ldap://localhost:389 LDAP_BIND_DN=cn=admin,dc=example,dc=com LDAP_BIND_PASSWORD=admin-password POSTGRES_READ_ONLY=true REDIS_READ_ONLY=true MYSQL_READ_ONLY=true MONGODB_READ_ONLY=true LDAP_READ_ONLY=true ``` --- ## 完整工具参考（113 个工具） ### 系统和管理工具（2） - `db_status`：检查连接状态（空闲、连接中、已连接、重试中、失败、断路器打开）、只读模式和所有已配置数据库的错误日志。 - `db_reload_config`：从磁盘热重载 `databases.config.yml` 并动态协调连接而不会中断活动查询。 ### Postgres 工具（30） - `pg_query`：执行只读 SELECT 查询（强制执行单个语句扩展查询协议）。 - `pg_execute_sql`：执行写 SQL 语句（INSERT、UPDATE、DELETE、DDL）。在只读模式下被阻止。 - `pg_list_tables`：列出目标模式中的表。 - `pg_describe_table`：检查列数据类型、序数位置和可空性。 - `pg_list_schemas`：列出所有数据库模式。 - `pg_list_views`：列出模式中的所有视图。 - `pg_list_indexes`：列出表和索引定义。 - `pg_list_triggers`：列出模式中的触发器和操作语句。 - `pg_table_stats`：获取总大小、表大小、索引大小和估计行数。 - `pg_list_constraints`：列出主键、外键和检查约束。 - `pg_explain_query`：使用 EXPLAIN 检查查询执行计划。 - `pg_active_queries`：从 `pg_stat_activity` 检索正在运行的非空闲查询和持续时间。 - `pg_list_functions`：列出用户定义函数、参数和返回类型。 - `pg_list_sequences`：列出模式中的序列对象。 - `pg_database_info`：获取数据库名称、当前用户、PostgreSQL 版本和数据库大小。 - `pg_kill_query`：通过 PID 终止正在运行的后端进程。在只读模式下被阻止。 - `pg_vacuum_analyze`：运行 VACUUM ANALYZE 以更新统计数据和回收死元组。在只读模式下被阻止。 - `pg_list_materialized_views`：列出模式中的物化视图。 - `pg_refresh_materialized_view`：刷新物化视图（支持 CONCURRENTLY）。在只读模式下被阻止。 - `pg_index_usage`：检查索引扫描次数和元组获取统计数据。 - `pg_lock_info`：检索活动数据库锁和查询持续时间。 - `pg_get_top_queries`：从 `pg_stat_statements` 获取慢速查询。 - `pg_explain_hypothetical_index`：使用 `hypopg` 模拟假设索引性能。 - `pg_database_health`：运行健康审计（连接利用率、缓冲区缓存命中率、死元组、复制滞后）。 - `pg_sizes_overview`：数据库、表和索引的存储大小分解。 - `pg_unused_indexes`：识别零扫描候选索引以删除。 - `pg_duplicate_indexes`：查找重叠或冗余索引。 - `pg_long_running_queries`：查找超过持续时间阈值的查询。 - `pg_missing_indexes`：识别需要索引的高顺序扫描表。 - `pg_bloat_estimate`：根据死元组计数估计表膨胀率。 ### Redis 工具（27） - `redis_get`：获取键的值。 - `redis_set`：设置键值。在只读模式下被阻止。 - `redis_mset`：设置多个键/值对在一个命令中（例如，用于播种）。在只读模式下被阻止。 - `redis_del`：删除键。在只读模式下被阻止。 - `redis_keys`：列出匹配全局模式的键（上限 1000 项）。 - `redis_ttl`：获取剩余的 TTL（秒）。 - `redis_hget`：获取哈希字段值。 - `redis_hset`：设置哈希字段值。在只读模式下被阻止。 - `redis_hdel`：删除哈希字段。在只读模式下被阻止。 - `redis_hgetall`：获取所有哈希字段和值。 - `redis_hexists`：检查哈希字段存在。 - `redis_sadd`：将成员添加到集合中。在只读模式下被阻止。 - `redis_srem`：从集合中删除成员。在只读模式下被阻止。 - `redis_smembers`：列出集合成员（上限 1000 项）。 - `redis_sismember`：测试集合成员资格。 - `redis_lpush`：在列表前添加元素。在只读模式下被阻止。 - `redis_rpush`：在列表后添加元素。在只读模式下被阻止。 - `redis_lpop`：删除并返回第一个列表元素。在只读模式下被阻止。 - `redis_rpop`：删除并返回最后一个列表元素。在只读模式下被阻止。 - `redis_lrange`：获取列表元素范围（上限 1000 项）。 - `redis_llen`：获取列表长度。 - `redis_exists`：检查键存在。 - `redis_expire`：设置键过期时间（秒）。在只读模式下被阻止。 - `redis_type`：检索键的数据类型。 - `redis_incr`：递增整数键。在只读模式下被阻止。 - `redis_decr`：递减整数键。在只读模式下被阻止。 - `redis_flushdb`：清除当前 Redis 数据库。在只读模式下被阻止。 ### Elasticsearch 工具（11） - `es_cluster_health`：获取状态（绿色/黄色/红色）、节点数和分片指标。 - `es_list_indices`：列出索引、文档数、存储大小和状态。 - `es_index_stats`：获取特定索引的详细指标。 - `es_search`：使用查询 DSL 执行搜索。 - `es_count`：计算匹配查询的文档数。 - `es_get_doc`：通过 ID 获取文档。 - `es_index_doc`：索引或覆盖文档。在只读模式下被阻止。 - `es_bulk_index`：将多个文档索引到一个索引中，使用单个 `_bulk` 请求，并报告每个文档的成功/失败情况（例如，用于播种）。在只读模式下被阻止。 - `es_update_doc`：部分更新文档字段。在只读模式下被阻止。 - `es_delete_doc`：通过 ID 删除文档。在只读模式下被阻止。 - `es_delete_by_query`：删除匹配查询 DSL 的文档。在只读模式下被阻止。 ### MySQL 工具（18） - `mysql_query`：执行只读 SELECT/SHOW/EXPLAIN 查询。 - `mysql_execute_sql`：执行写 SQL（INSERT、UPDATE、DELETE、DDL）。在只读模式下被阻止。 - `mysql_list_databases`：列出服务器上的数据库。 - `mysql_list_tables`：列出数据库中的表。 - `mysql_list_views`：列出视图和安全选项。 - `mysql_describe_table`：显示列定义和元数据。 - `mysql_show_create_table`：提取原始 `CREATE TABLE` DDL 语句。 - `mysql_show_create_view`：提取原始 `CREATE VIEW` DDL 语句。 - `mysql_list_indexes`：显示表索引（`SHOW INDEX`）。 - `mysql_list_triggers`：列出数据库触发器。 - `mysql_list_routines`：列出存储过程和函数。 - `mysql_list_constraints`：列出外键和约束。 - `mysql_table_stats`：检索估计的行数、数据长度和索引大小。 - `mysql_active_queries`：检索正在运行的线程（`SHOW FULL PROCESSLIST`）。 - `mysql_kill_query`：通过 ID 杀死正在运行的进程。在只读模式下被阻止。 - `mysql_explain_query`：分析查询执行计划（`EXPLAIN`）。 - `mysql_global_status`：查询服务器全局状态指标。 - `mysql_analyze_table`：运行 `ANALYZE TABLE` 以刷新统计数据。在只读模式下被阻止。 ### MongoDB 工具（19） - `mongo_list_databases`：列出 MongoDB 集群上的数据库。 - `mongo_list_collections`：列出数据库中的集合。 - `mongo_find`：使用筛选器、投影、排序、限制和跳过查询文档。 - `mongo_distinct`：获取唯一字段值。 - `mongo_aggregate`：执行 MongoDB 聚合管道。 - `mongo_count_documents`：计算匹配筛选器的文档数。 - `mongo_insert_one`：插入单个文档。在只读模式下被阻止。 - `mongo_insert_many`：插入文档数组。在只读模式下被阻止。 - `mongo_update_one`：更新匹配筛选器的单个文档。在只读模式下被阻止。 - `mongo_update_many`：更新多个文档。在只读模式下被阻止。 - `mongo_delete_one`：删除单个文档。在只读模式下被阻止。 - `mongo_delete_many`：删除多个文档。在只读模式下被阻止。 - `mongo_create_index`：创建集合索引。在只读模式下被阻止。 - `mongo_drop_index`：通过名称删除集合索引。在只读模式下被阻止。 - `mongo_list_indexes`：列出所有集合索引。 - `mongo_db_stats`：获取数据库存储统计数据。 - `mongo_collection_stats`：获取集合的存储、索引大小和对象计数。 - `mongo_explain`：获取查询计划执行计划和索引扫描指标。 - `mongo_server_status`：获取集群内存、连接和操作统计数据。 ### LDAP 工具（6） - `ldap_search`：通过基准 DN、筛选器和范围搜索目录（上限 500 条记录）。 - `ldap_compare`：比较属性/值对与条目。 - `ldap_add`：创建新条目。在只读模式下被阻止。 - `ldap_add_bulk`：创建多个条目，使用每个条目的成功/失败报告（例如，用于播种）。在只读模式下被阻止。 - `ldap_modify`：添加、替换或删除条目上的属性值。在只读模式下被阻止。 - `ldap_delete`：删除条目。在只读模式下被阻止。 --- ## 多连接 YAML 配置 对于具有多个命名数据库的复杂设置，请创建 `config/databases.config.yml`（复制 `config/databases.config.example.yml`）： ```yaml connections: - id: primary-pg type: postgres connectionString: ${POSTGRES_URL} defaultSchema: public statementTimeoutMs: 30000 readOnly: true - id: app-cache type: redis connectionString: ${REDIS_URL} readOnly: false - id: search-logs type: elasticsearch connectionString: ${ELASTICSEARCH_URL} apiVersion: "9" readOnly: true - id: legacy-cluster type: elasticsearch connectionString: ${LEGACY_ELASTICSEARCH_URL} apiVersion: "7" readOnly: true - id: analytics-mysql type: mysql connectionString: ${MYSQL_URL} statementTimeoutMs: 30000 readOnly: true - id: document-store type: mongodb connectionString: ${MONGODB_URL} defaultDatabase: production readOnly: true - id: directory type: ldap connectionString: ${LDAP_URL} bindDn: ${LDAP_BIND_DN} bindPassword: ${LDAP_BIND_PASSWORD} readOnly: false ``` --- ## 本地开发和自定义构建 ### 1. 本地构建和运行 ```bash git clone https://github.com/Nam088/mcp-database-server-v2.git cd mcp-database-server npm install npm run build # 将 TypeScript 编译到 dist/ npm test # 运行 Vitest 测试套件 ``` ### 2. 在 MCP 客户端中配置本地构建 ```json { "mcpServers": { "mcp-server-db": { "type": "stdio", "command": "node", "args": ["/absolute/path/to/mcp-database-server/dist/index.js"], "env": { "DATABASES_CONFIG_PATH": "/absolute/path/to/mcp-database-server/config/databases.config.yml" } } } } ``` ### 3. Claude Code CLI ```bash claude mcp add --scope user mcp-server-db node /absolute/path/to/mcp-database-server/dist/index.js --env DATABASES_CONFIG_PATH=/absolute/path/to/mcp-database-server/config/databases.config.yml ``` ### 客户端配置路径 - **Claude Desktop**：`~/Library/Application Support/Claude/claude_desktop_config.json` - **Claude Code（全局）**：`~/.claude.json` - **Gemini CLI / IDE**：`~/.gemini/config/mcp_config.json` - **Cursor / 项目根目录**：`.mcp.json` --- ## 许可证 在 MIT 许可证下分发。有关详细信息，请参见 [LICENSE](LICENSE)。