使用说明

⚠ 正在进行的工作分叉

此存储库是原始项目的一个正在进行的分支：

原始项目：mcp-db服务器来源： https://github.com/Souhar-dya/mcp-db-server 许可证：Apache许可证，版本2.0

此分叉正在进行调整，以供内部团队使用。它可能与上游项目存在显著差异，并不打算作为替代品。

⸻

此叉子的用途

此叉子的存在是为了： •扩展和定制内部工作流程的功能 •尝试上游项目中不存在的功能 •为团队特定工具提供基础

目前，它不打算公开分发或向上游捐款。

⸻

与上游的关系

此存储库包含对原始项目的修改。所有原始代码仍按照Apache许可证2.0版获得许可。

有关完整的许可证详细信息，请参阅LICENSE文件。

⸻

免责声明

这是一个内部衍生作品，与原始项目维护人员无关或没有得到他们的认可。

⸻

特性

多数据库支持：适用于PostgreSQL和MySQL
自然语言到SQL：使用HuggingFace转换器将纯英语查询转换为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（推荐）

克隆并启动服务：

git clone https://github.com/Souhar-dya/mcp-db-server.git
cd mcp-db-server
docker-compose up --build

测试端点：

# Health check
curl http://localhost:8000/health

# List tables
curl http://localhost:8000/mcp/list_tables

# Describe a table
curl http://localhost:8000/mcp/describe/customers

# Natural language query
curl -X POST "http://localhost:8000/mcp/query" \
  -H "Content-Type: application/json" \
  -d '{"nl_query": "show top 5 customers by total orders"}'

方案2：地方发展

先决条件：
- Python 3.11+
- PostgreSQL或MySQL数据库
安装依赖项：
```
pip install -r requirements.txt
```

设置环境变量：

export DATABASE_URL="postgresql+asyncpg://user:password@localhost:5432/dbname"
# or for MySQL:
# export DATABASE_URL="mysql+pymysql://user:password@localhost:3306/dbname"

运行服务器：
```
python -m app.server
```

示例数据库

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

客户：客户信息（10个样本客户）
订单：订单记录（17个样品订单）
订单项目：订单中的单个项目
订单_摘要：查看订单和客户数据的组合

自然语言查询示例

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

# 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`	服务器主机	`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

### 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云提供商来说 ssl-mode 驱动程序会忽略URL中的参数，但MCP服务器中始终为云连接启用SSL。

对于PostgreSQL，使用 sslmode=require 对于云数据库。对于MySQL，只需使用标准URL；SSL是自动处理的。

如果您看到以下错误 ssl-mode 或 sslmode，检查您的URL并确保您使用了正确的驱动程序前缀(mysql+aiomysql 或 postgresql+asyncpg).

云数据库示例

# Neon (PostgreSQL)
DATABASE_URL=postgresql+asyncpg://username:password@ep-xxxxxx-pooler.us-east-2.aws.neon.tech/dbname

# Aiven (MySQL)
DATABASE_URL=mysql+aiomysql://avnadmin:yourpassword@mysql-xxxxxx-username-xxxx.aivencloud.com:11079/defaultdb?ssl-mode=REQUIRED

Docker与Cloud DB的使用

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

故障排除

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


## Security Features

- **Read-Only Operations**: Only SELECT queries are allowed
- **Query Validation**: Automatic detection and blocking of dangerous SQL operations
- **Result Limiting**: Maximum 50 rows per query (configurable)
- **Input Sanitization**: Protection against SQL injection
- **Safe Defaults**: Secure configuration out of the box

## Architecture

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


## Model Context Protocol (MCP) Integration

This server is designed to work seamlessly with MCP-compatible AI agents:

1. **Standardized Endpoints**: RESTful API following MCP conventions
2. **Structured Responses**: JSON responses optimized for AI consumption
3. **Error Handling**: Consistent error messages and status codes
4. **Documentation**: OpenAPI/Swagger documentation available at `/docs`

## Deployment

### Docker Hub

```bash
# 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"}'

贡献

分叉存储库
创建功能分支(git checkout -b feature/amazing-feature)
提交您的更改(git commit -m 'Add some amazing feature')
推到分支(git push origin feature/amazing-feature)
打开拉取请求

许可证

此项目根据Apache许可证2.0获得许可-请参阅许可证文件以获取详细信息。

📝 更新日志

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列访问修复

固定的：已解决 Could not locate column in row for column 'column_name' MySQL数据库出错
固定的：已更改 describe_table 使用基于索引的行访问以获得更好的SQLAlchemy兼容性的方法
改进的：增强了模式自检的跨数据库兼容性
已解决：GitHub问题 #1

V1.0（2025-09-28）-异步错误修复

固定的：已解决 str can't be used in 'await' expression MCP服务器出错
改进的：NLP查询处理现在可以与Claude Desktop集成正常工作
增强：添加了全面的测试数据库设置脚本
更新：使用错误修复和更新的依赖关系重建Docker映像

v1.0.0（2025-09-25）-初始版本

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

致谢

快速API 优秀的web框架
拥抱面部变压器用于NL到SQL的功能
SQLAlchemy 用于数据库抽象
模型上下文协议（MCP）社区

支持

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