mcp-db-server

一个暴露关系数据库（PostgreSQL/MySQL）给AI代理并支持自然语言查询的MCP（模型上下文协议）服务器。将自然语言问题转换为SQL查询，并获取结构化结果。

功能

• 多数据库支持：支持PostgreSQL和MySQL
• 自然语言到SQL：使用HuggingFace transformers将纯英文查询转换为SQL
• RESTful API：基于FastAPI的干净数据库操作端点
• 安全第一：只读操作，带有查询验证和结果限制
• Docker就绪：完整的Docker Compose容器化
• 生产就绪：健康检查、日志记录和错误处理
• AI代理友好：专门设计用于AI代理集成

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
   docker-compose up --build
   

2. 测试端点：

   # 健康检查
   curl http://localhost:8000/health
   
   # 列出表
   curl http://localhost:8000/mcp/list_tables
   
   # 描述一个表
   curl http://localhost:8000/mcp/describe/customers
   
   # 自然语言查询
   curl -X POST "http://localhost:8000/mcp/query" \
     -H "Content-Type: application/json" \
     -d '{"nl_query": "显示按总订单量排名前五的客户"}'
   

方案2：本地开发

1. 前提条件：

   • Python 3.11+
   • PostgreSQL或MySQL数据库

2. 安装依赖项：

   pip install -r requirements.txt
   

3. 设置环境变量：

   export DATABASE_URL="postgresql+asyncpg://user:password@localhost:5432/dbname"
   # 或对于MySQL：
   # export DATABASE_URL="mysql+pymysql://user:password@localhost:3306/dbname"
   

4. 运行服务器：

   python -m app.server
   

示例数据库

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

• customers：客户信息（10个样本客户）
• orders：订单记录（17个样本订单）
• order_items：订单中的单个商品
• order_summary：结合订单和客户数据的视图

自然语言查询示例

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

# 获取所有客户
curl -X POST "http://localhost:8000/mcp/query" \
  -H "Content-Type: application/json" \
  -d '{"nl_query": "显示所有客户"}'

# 按状态计数订单
curl -X POST "http://localhost:8000/mcp/query" \
  -H "Content-Type:_application/json" \
  -d '{"nl_query": "按状态计数订单"}'

# 按订单金额排名前五的客户
curl -X POST "http://localhost:8000/mcp/query" \
  -H "Content-Type: application/json" \
  -d '{"nl_query": "按总订单金额排名前五的客户"}'

# 最近的订单
curl -X POST "http://localhost:8000/mcp/query" \
  -H "Content-Type: application/json" \
  -d '{"nl_query": "显示上周的最近订单"}'

配置

环境变量

变量	描述	默认值
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	服务器主机	0.0.0.0
PORT	服务器端口	8000

数据库连接示例

# 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

安全特性

• 只读操作：仅允许SELECT查询
• 查询验证：自动检测并阻止危险的SQL操作
• 结果限制：每个查询最多返回50行（可配置）
• 输入净化：防止SQL注入
• 安全默认设置：开箱即用的安全配置

架构

mcp-db-server/
├── app/
│   ├── __init__.py          # 包初始化
│   ├── server.py            # FastAPI应用程序和端点
│   ├── db.py                # 数据库连接和操作
│   └── nl_to_sql.py         # 自然语言到SQL转换
├── .github/workflows/
│   └── docker-publish.yml   # CI/CD流水线
├── docker-compose.yml       # Docker Compose配置
├── Dockerfile               # 容器定义
├── init_db.sql             # 示例数据库模式和数据
├── requirements.txt         # Python依赖项
└── README.md               # 本文件

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

此服务器旨在与兼容MCP的AI代理无缝工作：

1. 标准化端点：遵循MCP惯例的RESTful API
2. 结构化响应：优化供AI消费的JSON响应
3. 错误处理：一致的错误消息和状态码
4. 文档：在/docs处提供OpenAPI/Swagger文档

部署

Docker Hub

# 拉取最新镜像
docker pull souhardyak/mcp-db-server:latest

# 使用您的数据库运行
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

测试

在本地运行测试

# 启动测试数据库
docker-compose up postgres -d

# 等待数据库准备好
sleep 10

# 运行测试
python -m pytest tests/ -v

手动测试

# 测试健康端点
curl http://localhost:8000/health

# 测试表列出
curl http://localhost:8000/mcp/list_tables

# 测试自然语言查询
curl -X POST "http://localhost:8000/mcp/query" \
  -H "Content-Type: application/json" \
  -d '{"nl_query": "显示来自加利福尼亚的所有客户"}'

贡献

1. 分叉仓库
2. 创建功能分支 (git checkout -b feature/amazing-feature)
3. 提交更改 (git commit -m '添加一些惊人的功能')
4. 推送到分支 (git push origin feature/amazing-feature)
5. 打开拉取请求

许可证

本项目根据Apache许可证2.0发布 - 查看LICENSE文件以获取详细信息。

更新日志

v1.1.0 (2025-09-28) - 异步Bug修复

• 修复：解决了MCP服务器中str不能用于'await'表达式的错误
• 改进：NLP查询处理现在与Claude Desktop集成正确工作
• 增强：添加了全面的测试数据库设置脚本
• 更新：Docker镜像重建，修复了bug并更新了依赖项

v1.0.0 (2025-09-25) - 初始发布

• 初始：完整的MCP数据库服务器实现
• 添加：带有FastAPI的RESTful API
• 添加：自然语言到SQL转换
• 添加：Docker容器化和部署
• 添加：多数据库支持（PostgreSQL、MySQL、SQLite）

致谢

• FastAPI 作为优秀的Web框架
• HuggingFace Transformers 用于NL到SQL的能力
• SQLAlchemy 用于数据库抽象
• 模型上下文协议（MCP）社区

支持

• 报告问题
• 讨论
• 文档

---

⭐ 如果这个项目帮助了您，请考虑给它一个星！