MCP Database Server

mcp-db-server

一个 MCP（Model Context Protocol）服务，可将关系型数据库（PostgreSQL/MySQL）提供给支持自然语言查询的 AI Agent。将自然语言问题转换为 SQL 查询，并获取结构化结果。

功能

• 多数据库支持：支持 PostgreSQL 和 MySQL
• 自然语言转 SQL：使用 HuggingFace transformers 将普通英语查询转换为 SQL
• RESTful API：基于 FastAPI 的简洁数据库操作端点
• 安全优先：只读操作，并提供查询验证和结果限制
• 支持 Docker：通过 Docker Compose 完整容器化
• 可用于生产环境：健康检查、日志记录和错误处理
• 便于 AI Agent 集成：专为 AI Agent 集成设计

版本 1.4.0 变更

• 为所有数据库 HTTP 端点添加了强制的 X-API-Key 身份验证；/health 仍公开提供健康检查。
• 移除了不受限制的凭据 CORS，并将允许的来源设为可显式配置。
• 将默认 HTTP 绑定地址更改为 127.0.0.1。
• 添加了针对现有数据库表的表名验证，以阻止通过表路由进行 SQL 注入。
• 添加了对 PostgreSQL sslmode=require 的兼容支持，以用于 asyncpg 连接。
• 更新了 Docker Compose、环境变量示例和文档，说明安全配置 API 密钥。
• 发布了 Docker 镜像：
  • souhardyak/mcp-db-server:1.4.0
  • souhardyak/mcp-db-server:latest
• 添加了 GitHub Container Registry 发布支持：
  • ghcr.io/souhar-dya/mcp-db-server:1.4.0
  • ghcr.io/souhar-dya/mcp-db-server:latest

API 端点

端点	方法	描述
/health	GET	健康检查和服务状态
/mcp/list_tables	GET	列出所有可用表及其列数
/mcp/describe/{table_name}	GET	获取特定表的详细架构
/mcp/query	POST	执行自然语言查询
/mcp/tables/{table_name}/sample	GET	获取表中的示例数据

快速开始

选项 1：Docker Compose（推荐）

1. 克隆并启动服务：

   git clone https://github.com/Souhar-dya/mcp-db-server.git
   cd mcp-db-server
   export MCP_API_KEY="$(openssl rand -hex 32)"
   docker-compose up --build
   

2. 测试端点：

   # Health check
   curl http://localhost:8000/health
   
   # List tables (requires the configured API key)
   curl -H "X-API-Key: $MCP_API_KEY" http://localhost:8000/mcp/list_tables
   
   # Describe a table
   curl -H "X-API-Key: $MCP_API_KEY" http://localhost:8000/mcp/describe/customers
   
   # Natural language query
   curl -X POST "http://localhost:8000/mcp/query" \
     -H "X-API-Key: $MCP_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"nl_query": "show top 5 customers by total orders"}'
   

选项 2：本地开发

1. 前提条件：

   • Python 3.11+
   • PostgreSQL 或 MySQL 数据库

2. 安装依赖：

   pip install -r requirements.txt
   

3. 设置环境变量：

   export DATABASE_URL="postgresql+asyncpg://user:password@localhost:5432/dbname"
   export MCP_API_KEY="$(openssl rand -hex 32)"
   # or for MySQL:
   # export DATABASE_URL="mysql+pymysql://user:password@localhost:3306/dbname"
   

4. 运行服务：

   python -m app.server
   

示例数据库

项目包含一个具有真实电商数据的示例数据库：

• customers：客户信息（10 位示例客户）
• orders：订单记录（17 笔示例订单）
• order_items：订单中的各个商品
• order_summary：整合订单和客户数据的视图

自然语言查询示例

服务可以理解各种类型的自然语言查询：

# Get all customers
curl -X POST "http://localhost:8000/mcp/query" \
  -H "Content-Type: application/json" \
  -d '{"nl_query": "show all customers"}'

# Count orders by status
curl -X POST "http://localhost:8000/mcp/query" \
  -H "Content-Type: application/json" \
  -d '{"nl_query": "count orders by status"}'

# Top customers by order value
curl -X POST "http://localhost:8000/mcp/query" \
  -H "Content-Type: application/json" \
  -d '{"nl_query": "top 5 customers by total order amount"}'

# Recent orders
curl -X POST "http://localhost:8000/mcp/query" \
  -H "Content-Type: application/json" \
  -d '{"nl_query": "show recent orders from last week"}'

配置

环境变量

变量	说明	默认值
DATABASE_URL	完整的数据库连接 URL	postgresql+asyncpg://postgres:postgres@localhost:5432/postgres
DB_HOST	数据库主机	localhost
DB_PORT	数据库端口	5432
DB_USER	数据库用户名	postgres
DB_PASSWORD	数据库密码	postgres
DB_NAME	数据库名称	postgres
HOST	服务主机	127.0.0.1
PORT	服务端口	8000
MCP_API_KEY	数据库 HTTP 路由所需的 API 密钥	未设置（API 已禁用）
CORS_ALLOW_ORIGINS	以逗号分隔的允许访问的浏览器源	空（已禁用）

数据库连接示例

# PostgreSQL
DATABASE_URL=postgresql+asyncpg://user:pass@localhost:5432/mydb

# MySQL
DATABASE_URL=mysql+pymysql://user:pass@localhost:3306/mydb

# PostgreSQL with SSL
DATABASE_URL=postgresql+asyncpg://user:pass@localhost:5432/mydb?sslmode=require

### Database Connection Examples

```bash
# PostgreSQL (local or cloud)
DATABASE_URL=postgresql+asyncpg://user:password@host:5432/dbname

# MySQL (local or cloud)
DATABASE_URL=mysql+aiomysql://user:password@host:3306/dbname

# PostgreSQL with SSL (cloud, e.g. Neon, Supabase, Aiven)
DATABASE_URL=postgresql+asyncpg://user:password@host:5432/dbname?sslmode=require

# MySQL with SSL (cloud, e.g. Aiven, PlanetScale)
DATABASE_URL=mysql+aiomysql://user:password@host:3306/dbname?ssl-mode=REQUIRED

注意：

• 对于 MySQL 云服务提供商，驱动程序会忽略 URL 中的 ssl-mode 参数，但 MCP 服务始终会为云连接启用 SSL。
• 对于 PostgreSQL 云数据库，请使用 sslmode=require。对于 MySQL，使用标准 URL 即可；SSL 会自动处理。
• 如果看到有关 ssl-mode 或 sslmode 的错误，请检查 URL，并确保使用了正确的驱动程序前缀（mysql+aiomysql 或 postgresql+asyncpg）。

云数据库示例

# Neon (PostgreSQL)
DATABASE_URL=postgresql+asyncpg://username:[email protected]/dbname

# Aiven (MySQL)
DATABASE_URL=mysql+aiomysql://avnadmin:[email protected]:11079/defaultdb?ssl-mode=REQUIRED

使用云数据库运行 Docker

docker run -d \
  -p 8000:8000 \
  -e DATABASE_URL="<your_cloud_database_url>" \
  -e MCP_API_KEY="<your_random_api_key>" \
  souhardyak/mcp-db-server:latest

也可通过 GitHub Container Registry 获取：

docker login ghcr.io
docker pull ghcr.io/souhar-dya/mcp-db-server:latest
docker run -d \
  -p 8000:8000 \
  -e DATABASE_URL="<your_database_url>" \
  -e MCP_API_KEY="$MCP_API_KEY" \
  ghcr.io/souhar-dya/mcp-db-server:latest

推送 v*.*.* 标签时会自动发布镜像。工作流还会创建对应的 GitHub Release。若要发布现有标签（例如 v1.4.0），请打开工作流的 Run workflow 操作并输入 1.4.0。如果希望允许未经身份验证的拉取，请在仓库的 Packages 设置中将 GHCR 软件包的可见性设为 Public。

故障排除

• 如果出现 connect() got an unexpected keyword argument 'ssl-mode'，请忽略此错误：SSL 仍处于启用状态。
• 如果出现网络错误，请检查防火墙和数据库凭据。
• 对于 MySQL，URL 中始终使用 mysql+aiomysql 以支持异步操作。

### PostgreSQL SSL connection note

For PostgreSQL cloud providers, use an asyncpg URL and `sslmode=require`:

```bash
DATABASE_URL=postgresql+asyncpg://user:password@host:5432/dbname?sslmode=require

服务会将 sslmode=require 标准化为 asyncpg 所需的 ssl 选项。我们已使用 CREATE、INSERT、SELECT、UPDATE、DELETE 和 DROP，成功对兼容的云数据库完成临时 PostgreSQL 验证；未保留任何测试数据。切勿提交或分享包含真实密码的连接 URL。

API 密钥身份验证

MCP_API_KEY 是由你生成并提供给服务的机密。它通过 X-API-Key 请求头保护所有数据库 HTTP 端点。/health 端点仍保持公开，以用于容器健康检查。

在 Linux 或 macOS 上生成强密钥：

export MCP_API_KEY="$(openssl rand -hex 32)"

在 Windows PowerShell 中生成密钥：

$bytes = New-Object byte[] 32
[Security.Cryptography.RandomNumberGenerator]::Create().GetBytes($bytes)
$env:MCP_API_KEY = ([BitConverter]::ToString($bytes) -replace "-", "").ToLower()

使用该密钥启动 Docker 镜像：

docker run -d \
  -p 8000:8000 \
  -e DATABASE_URL="<your_database_url>" \
  -e MCP_API_KEY="$MCP_API_KEY" \
  souhardyak/mcp-db-server:latest

使用相同密钥调用受保护的端点：

curl -H "X-API-Key: $MCP_API_KEY" http://localhost:8000/mcp/list_tables

请将密钥保存在密码管理器或部署机密存储中。不要将其提交到 Git、放入公开镜像或写入日志。

安全功能

• 强制 HTTP 身份验证：数据库 API 路由需要 X-API-Key；/health 仍可公开访问，用于健康检查
• 安全的网络默认设置：HTTP 模式默认绑定到 127.0.0.1，除非另有明确配置
• 受限的 CORS：除非明确配置来源，否则禁用跨域访问
• 只读操作：仅允许 SELECT 查询
• 查询验证：自动检测并阻止危险的 SQL 操作
• 结果限制：每次查询最多返回 50 行（可配置）
• 输入净化：防范 SQL 注入
• 安全默认设置：开箱即用的安全配置

架构

mcp-db-server/
├── app/
│   ├── __init__.py          # Package initialization
│   ├── server.py            # FastAPI application and endpoints
│   ├── db.py                # Database connection and operations
│   └── nl_to_sql.py         # Natural language to SQL conversion
├── .github/workflows/
│   └── docker-publish.yml   # CI/CD pipeline
├── docker-compose.yml       # Docker Compose configuration
├── Dockerfile               # Container definition
├── init_db.sql             # Sample database schema and data
├── requirements.txt         # Python dependencies
└── README.md               # This file

模型上下文协议（MCP）集成

此服务旨在与兼容 MCP 的 AI Agent 无缝协作：

1. 标准化端点：遵循 MCP 约定的 RESTful API
2. 结构化响应：针对 AI 使用进行了优化的 JSON 响应
3. 错误处理：一致的错误消息和状态代码
4. 文档：可在 /docs 查看 OpenAPI/Swagger 文档

发布到 VS Code MCP 商店（注册表）

VS Code MCP 画廊使用 MCP Registry 元数据。此仓库现已包含用于发布到注册表的 server.json。

1) 构建并发布 Docker 镜像

docker build -t souhardyak/mcp-db-server:1.3.1 .
docker push souhardyak/mcp-db-server:1.3.1

2) 验证服务元数据

server.json 已配置为 OCI 软件包和 stdio 传输：

• name：io.github.Souhar-dya/mcp-db-server
• registryType：oci
• identifier：docker.io/souhardyak/mcp-db-server:1.3.1

Dockerfile 包含注册表所有权注解：

• io.modelcontextprotocol.server.name=io.github.Souhar-dya/mcp-db-server

3) 发布到 MCP Registry

安装发布工具并发布元数据：

mcp-publisher login github
mcp-publisher publish

发布后，用户可以从兼容 MCP 的客户端（包括读取该注册表的 VS Code MCP 体验）中发现并安装它。

4) 本地 VS Code 配置示例

{
  "servers": {
    "mcp-db-server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "DATABASE_URL=sqlite+aiosqlite:////data/default.db",
        "souhardyak/mcp-db-server:1.3.1"
      ]
    }
  }
}

Docker 冒烟测试

使用 tests/docker 中专用的 Docker 冒烟测试：

python tests/docker/smoke_test.py

此测试会验证 Docker 守护进程访问、镜像构建、容器启动和健康状态。

部署

Docker Hub

# Pull the latest image
docker pull souhardyak/mcp-db-server:latest

# Run with your database
docker run -d \
  -p 8000:8000 \
  -e DATABASE_URL="your_database_url_here" \
  souhardyak/mcp-db-server:latest

Kubernetes

apiVersion: apps/v1
kind: Deployment
metadata:
  name: mcp-db-server
spec:
  replicas: 3
  selector:
    matchLabels:
      app: mcp-db-server
  template:
    metadata:
      labels:
        app: mcp-db-server
    spec:
      containers:
        - name: mcp-db-server
          image: souhardyak/mcp-db-server:latest
          ports:
            - containerPort: 8000
          env:
            - name: DATABASE_URL
              valueFrom:
                secretKeyRef:
                  name: db-secret
                  key: url
---
apiVersion: v1
kind: Service
metadata:
  name: mcp-db-server-service
spec:
  selector:
    app: mcp-db-server
  ports:
    - port: 80
      targetPort: 8000
  type: LoadBalancer

测试

在本地运行测试

# Start test database
docker-compose up postgres -d

# Wait for database to be ready
sleep 10

# Run tests
python -m pytest tests/ -v

手动测试

# Test health endpoint
curl http://localhost:8000/health

# Test table listing
curl http://localhost:8000/mcp/list_tables

# Test natural language query
curl -X POST "http://localhost:8000/mcp/query" \
  -H "Content-Type: application/json" \
  -d '{"nl_query": "show me all customers from California"}'

参与贡献

1. Fork 此仓库
2. 创建功能分支（git checkout -b feature/amazing-feature）
3. 提交更改（git commit -m 'Add some amazing feature'）
4. 推送到该分支（git push origin feature/amazing-feature）
5. 发起 Pull Request

许可证

本项目采用 Apache License 2.0 许可，详情请参阅 LICENSE 文件。

📝 更新日志

v1.3.0（2025-12-24）- Docker 路径修复

• 已修复：解决 Docker 容器中的导入路径问题，该问题会导致 from db import DatabaseManager 失败
• 已修复：将 Dockerfile 和 docker-compose.yml 健康检查中的相对路径改为绝对路径
• 已改进：mcp_server.py 现在使用稳健的路径解析方式，可在本地和 Docker 容器中正常工作
• 已更新：重建 Docker 镜像并推送，包含所有路径修复

v1.2.0（2025-11-03）- MySQL 列访问修复

• 已修复：解决 MySQL 数据库中的 Could not locate column in row for column 'column_name' 错误
• 已修复：更改 describe_table 方法，使用基于索引的行访问方式，以提升 SQLAlchemy 兼容性
• 已改进：增强跨数据库的架构内省兼容性
• 已解决：GitHub Issue #1

v1.1.0（2025-09-28）- 异步错误修复

• 已修复：解决 MCP 服务中的 str can't be used in 'await' expression 错误
• 已改进：NLP 查询处理现已可与 Claude Desktop 集成正常工作
• 已增强：添加全面的测试数据库设置脚本
• 已更新：重建 Docker 镜像，包含错误修复和更新后的依赖项

v1.0.0（2025-09-25）- 首次发布

• 初始版本：完整实现 MCP 数据库服务
• 新增：基于 FastAPI 的 RESTful API
• 新增：自然语言转 SQL
• 新增：Docker 容器化与部署
• 新增：支持多种数据库（PostgreSQL、MySQL、SQLite）

致谢

• 感谢 FastAPI 提供出色的 Web 框架
• 感谢 HuggingFace Transformers 提供自然语言转 SQL 功能
• 感谢 SQLAlchemy 提供数据库抽象
• 感谢 Model Context Protocol（MCP）社区

支持

• 报告问题
• 讨论
• 文档

---

⭐ 如果这个项目对你有帮助，请考虑为它点亮一颗星！