postgres-mysql-mcp-server

🚀 MCP SQL Server

MCP SQL Server 是一个用于查询 PostgreSQL 和 MySQL 数据库的模型上下文协议（MCP）服务器。它能让代码编辑器中的 AI 助手安全地与数据库交互，帮助开发者更高效地进行数据库相关的开发工作。

🚀 快速开始

推荐方式：使用 npx 无需安装即可运行：

npx postgres-mysql-mcp-server

对于 MCP 客户端配置（如 Cursor、Windsurf 等），可使用以下配置：

{
  "mcpServers": {
    "sql": {
      "command": "npx",
      "args": ["-y", "postgres-mysql-mcp-server"],
      "env": {
        "DB_TYPE": "postgresql",
        "DB_HOST": "localhost",
        "DB_PORT": "5432",
        "DB_DATABASE": "mydb",
        "DB_USER": "postgres",
        "DB_PASSWORD": "password"
      }
    }
  }
}

✨ 主要特性

• 可连接到 PostgreSQL 和 MySQL 数据库。
• 执行 SQL 查询。
• 列出数据库中的所有表。
• 描述表结构。
• 支持参数化查询。
• 采用连接池提高性能。
• 通过环境变量进行安全的凭证管理。
• 当设置环境变量时，服务器启动时自动连接。

📦 安装指南

选项 1：使用 npx（推荐 - 无需安装）

推荐直接使用 npx 运行服务器，无需进行任何安装。这是最简单、最便捷的方法：

npx postgres-mysql-mcp-server

npx 会自动处理 -y 标志，因此它将在不提示的情况下下载并运行最新版本。

选项 2：通过 npm 安装

如果你想安装该包，可以选择以下方式： 全局安装：

npm install -g postgres-mysql-mcp-server

在项目中本地安装：

npm install postgres-mysql-mcp-server

选项 3：开发环境安装

若要进行本地开发或贡献代码，请执行以下操作：

git clone https://github.com/TranChiHuu/postgres-mysql-mcp-server.git
cd postgres-mysql-mcp-server
npm install

💻 使用示例

运行服务器

服务器通过标准输入输出运行，并通过 MCP 协议进行通信。 推荐：使用 npx（无需安装）

npx postgres-mysql-mcp-server

这是运行服务器的推荐方式。npx 将自动下载并运行最新版本。 替代方法：使用全局安装的包

postgres-mysql-mcp-server

本地开发时：

npm start

可用工具

1. connect_database

连接到 PostgreSQL 或 MySQL 数据库。参数可以直接提供、从环境变量加载，或两者结合使用。如果设置了环境变量，服务器将在启动时自动连接。 参数（如果使用环境变量，所有参数可选）：

• type（字符串，可选）：数据库类型 - "postgresql" 或 "mysql"
• host（字符串，可选）：数据库主机
• port（数字，可选）：数据库端口
• database（字符串，可选）：数据库名称
• user（字符串，可选）：数据库用户
• password（字符串，可选）：数据库密码
• ssl（布尔值，可选）：使用 SSL 连接（默认：false）

示例： 使用参数：

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

使用环境变量（无参数调用）：

{}

参数与环境变量混合使用：

{
  "type": "postgresql",
  "host": "custom-host"
}

2. execute_query

在已连接的数据库上执行 SQL 查询。 参数：

• query（字符串，必需）：要执行的 SQL 查询
• params（数组，可选）：参数化查询的查询参数

示例：

{
  "query": "SELECT * FROM users WHERE id = $1",
  "params": [123]
}

3. list_tables

列出已连接数据库中的所有表。 参数：无

4. describe_table

获取特定表的结构信息。 参数：

• tableName（字符串，必需）：要描述的表名

示例：

{
  "tableName": "users"
}

5. disconnect_database

断开与当前数据库的连接。 参数：无

📚 详细文档

配置

环境变量

你可以使用环境变量来配置数据库连接。在项目根目录创建 .env 文件或设置环境变量：

选项 1：通用环境变量（适用于 PostgreSQL 和 MySQL）

DB_TYPE=postgresql          # 或 "mysql"
DB_HOST=localhost
DB_PORT=5432
DB_DATABASE=mydb
DB_USER=postgres
DB_PASSWORD=password
DB_SSL=false               # 可选，设置为 "true" 使用 SSL

选项 2：PostgreSQL 特定环境变量

POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_DATABASE=mydb
POSTGRES_USER=postgres
POSTGRES_PASSWORD=password
POSTGRES_SSL=false         # 可选

选项 3：MySQL 特定环境变量

MYSQL_HOST=localhost
MYSQL_PORT=3306
MYSQL_DATABASE=mydb
MYSQL_USER=root
MYSQL_PASSWORD=password
MYSQL_SSL=false            # 可选

注意：如果设置了环境变量，服务器将在启动时自动连接。你也可以在不提供参数的情况下调用 connect_database 来使用环境变量，或者提供部分参数与环境变量合并使用。

MCP 客户端配置

此 MCP 服务器可与支持 AI 的代码编辑器无缝集成。将其添加到你的 MCP 客户端配置中，以启用支持数据库的 AI 辅助功能。

支持的编辑器

• Cursor - 支持 AI 的代码编辑器
• Windsurf - 以 AI 为先的 IDE
• 任何支持模型上下文协议的编辑器

配置步骤

对于 Cursor：

1. 打开 Cursor 设置。
2. 导航到功能 → 模型上下文协议。
3. 添加以下服务器配置。

对于 Windsurf：

1. 打开设置。
2. 导航到 MCP 服务器。
3. 添加以下服务器配置。

对于其他支持 MCP 的编辑器： 将配置添加到你的 MCP 设置文件（通常为 ~/.config/mcp/settings.json 或编辑器特定位置）。

配置选项

选项 1：使用 npx（推荐 - 无需安装）

这是推荐的配置方式。npx 会自动下载并运行最新版本，无需任何安装：

{
  "mcpServers": {
    "sql": {
      "command": "npx",
      "args": ["-y", "postgres-mysql-mcp-server"],
      "env": {
        "DB_TYPE": "postgresql",
        "DB_HOST": "localhost",
        "DB_PORT": "5432",
        "DB_DATABASE": "mydb",
        "DB_USER": "postgres",
        "DB_PASSWORD": "password"
      }
    }
  }
}

使用 npx 的好处：

• ✅ 无需安装
• ✅ 始终使用最新版本
• ✅ 无需手动更新
• ✅ 可在不同项目中使用，无冲突
• ✅ -y 标志会自动回答安装提示为 "是"

选项 2：使用全局安装的包

如果你已全局安装该包（npm install -g postgres-mysql-mcp-server）：

{
  "mcpServers": {
    "sql": {
      "command": "postgres-mysql-mcp-server",
      "env": {
        "DB_TYPE": "postgresql",
        "DB_HOST": "localhost",
        "DB_PORT": "5432",
        "DB_DATABASE": "mydb",
        "DB_USER": "postgres",
        "DB_PASSWORD": "password"
      }
    }
  }
}

选项 3：使用本地安装的包

如果你已在项目中本地安装该包（npm install postgres-mysql-mcp-server）：

{
  "mcpServers": {
    "sql": {
      "command": "node",
      "args": ["./node_modules/postgres-mysql-mcp-server/index.js"],
      "env": {
        "DB_TYPE": "postgresql",
        "DB_HOST": "localhost",
        "DB_PORT": "5432",
        "DB_DATABASE": "mydb",
        "DB_USER": "postgres",
        "DB_PASSWORD": "password"
      }
    }
  }
}

选项 4：开发环境设置（用于本地开发）

如果你正在进行本地开发并克隆了仓库：

{
  "mcpServers": {
    "sql": {
      "command": "npm",
      "args": ["start"],
      "cwd": "/path-to-source/postgres-mysql-mcp-server",
      "env": {
        "DB_TYPE": "postgresql",
        "DB_HOST": "localhost",
        "DB_PORT": "5432",
        "DB_DATABASE": "mydb",
        "DB_USER": "postgres",
        "DB_PASSWORD": "password"
      }
    }
  }
}

示例：与 Cursor AI 配合使用

配置完成后，你可以通过自然语言与数据库进行交互：

你："我的数据库中有哪些表？"
AI：[使用 list_tables 工具] "你的数据库包含：users、orders、products、categories"

你："给我展示 users 表的结构"
AI：[使用 describe_table 工具] "users 表包含：id（整数）、email（可变字符）、created_at（时间戳）..."

你："创建一个通过 ID 获取用户的 API 端点"
AI：[使用 describe_table 了解表结构，然后生成代码]
    "这是与你的 users 表结构匹配的端点..."

AI 助手会自动使用适当的 MCP 工具查询你的数据库，并提供准确的、支持表结构的响应。

开发

该项目使用纯 JavaScript（ES 模块），因此无需构建步骤。只需编辑 index.js 并运行 npm start。

安全注意事项

⚠️ 重要提示

• 切勿将数据库凭证提交到版本控制中。
• 使用环境变量或安全的凭证管理方式。
• 服务器支持 SSL 连接，以实现安全的数据库访问。
• 在生产环境中始终验证和清理 SQL 查询。

要求

• Node.js 18+
• 可访问 PostgreSQL 或 MySQL 数据库

贡献

欢迎贡献代码！请随时提交拉取请求。

📄 许可证

本项目采用 MIT 许可证。