使用说明

数据库MCP服务器

一种通过标准化接口提供数据库操作的模型上下文协议（MCP）服务器。此服务器使AI助手和其他MCP客户端能够使用自然语言命令与MySQL数据库进行交互。

特性

数据库反思：列出表、描述模式并获取表统计信息
CRUD操作：为用户、产品和订单创建、读取、更新和删除操作
安全SQL执行：执行带有内置安全检查的SELECT查询
健康监测：数据库连接测试
分页支持：高效处理大型数据集
搜索功能：跨用户数据的模糊搜索

快速开始

先决条件

Python 3.8+
MySQL数据库服务器
MCP兼容客户端（克劳德桌面等）

安装

克隆仓库

git clone <repository-url>
cd database-mcp

安装依赖项
```
pip install -r requirements.txt
```

配置数据库连接

创建 .env 项目根目录中的文件：

DB_USER=your_username
DB_PASSWORD=your_password
DB_HOST=127.0.0.1
DB_PORT=3306
DB_NAME=your_database_name

初始化数据库表

服务器在启动时使用SQLAlchemy模型自动创建表。

运行服务器

python main.py

服务器将启动并监听MCP连接。

数据库模式

服务器管理以下表：

用户(`user`)

id （主键）
name （字符串，50个字符）
email （字符串，50个字符，唯一）
password （字符串，100个字符）

产品中心(`product`)

id （主键）
name （字符串，100个字符）
price （浮动）
stock （整数）

订单(`order_list`)

id （主键）
user_id （外键→ user.id）
product_id （外键→ product.id）
quantity （整数）

附加表格

chat_history -对话记录
chat_summary -会议摘要
chat_user -聊天会话用户
reminders -用户提醒
recommendations -系统建议

可用工具

数据库反思

health_check() -测试数据库连接
list_tables() -获取所有表名
describe_table(table) -获取表架构详细信息
table_count(table) -统计表中的行数
sample_rows(table, limit=5) -获取样本数据

SQL 执行

run_sql_select(sql, max_rows=1000) -安全执行SELECT查询

用户管理

user_create(name, email, password) -创建新用户
user_get(id=None, email=None) -通过ID或电子邮件获取用户
user_list(limit=100, offset=0, q=None) -列出具有搜索功能的用户
user_exists(email) -检查用户是否存在
user_update(id, updates) -更新用户字段
user_delete(id) -删除用户

产品管理

product_create(name, price, stock) -创建新产品
product_get(id) -按ID获取产品
product_list(limit=100, offset=0, q=None) -通过搜索列出产品
product_update(id, updates) -更新产品字段
product_delete(id) -删除产品

订单管理

order_create(user_id, product_id, quantity) -创建新订单
order_get(id) -按ID获取订单
order_list(limit=100, offset=0, user_id=None) -列出订单
order_update(id, updates) -更新订单
order_delete(id) -删除订单

用法示例

基本数据库操作

# Check database health
health_check()
# Returns: {"ok": true}

# List all tables
list_tables()
# Returns: ["user", "product", "order_list", ...]

# Get table schema
describe_table("user")
# Returns detailed column information

用户操作

# Create a user
user_create("John Doe", "john@example.com", "password123")

# Find user by email
user_get(email="john@example.com")

# Search users
user_list(q="john", limit=10)

# Update user
user_update(1, {"name": "John Smith"})

产品运营

# Create product
product_create("Laptop", 999.99, 50)

# List products with search
product_list(q="laptop", limit=20)

# Update stock
product_update(1, {"stock": 45})

订单操作

# Create order
order_create(user_id=1, product_id=1, quantity=2)

# Get user's orders
order_list(user_id=1)

MCP客户端配置

克劳德桌面版

添加到您的Claude Desktop配置中：

{
  "mcpServers": {
    "database": {
      "command": "python",
      "args": ["path/to/database-mcp/main.py"],
      "env": {
        "DB_USER": "your_username",
        "DB_PASSWORD": "your_password",
        "DB_HOST": "127.0.0.1",
        "DB_PORT": "3306",
        "DB_NAME": "your_database"
      }
    }
  }
}

安全功能

SQL注入保护：使用参数化查询
只读SQL: run_sql_select 只允许SELECT语句
行限制：自动分页和行数限制
输入验证：类型检查和边界验证

错误处理

服务器包括全面的错误处理：

数据库连接失败
SQL查询无效
缺少记录
约束违反

所有错误都会被记录下来，并返回用户友好的消息。

发展

项目结构

database-mcp/
├── main.py              # MCP server implementation
├── database.py          # Database connection setup
├── models.py            # SQLAlchemy models
├── requirements.txt     # Python dependencies
├── .env                 # Environment configuration
└── schemas/             # Pydantic schemas (optional)
    ├── user_schema.py
    ├── product_schema.py
    └── order_schema.py

添加新模型

在中定义模型 models.py
在中添加CRUD工具 main.py
根据需要更新数据库架构

测试

测试数据库连接：

python -c "from main import health_check; print(health_check())"

故障排除

常见问题

连接被拒绝

检查MySQL服务器是否正在运行
验证中的连接凭据 .env
确保数据库存在

导入错误

安装所有要求： pip install -r requirements.txt
检查Python版本兼容性

权限不足

验证数据库用户是否具有必要的权限
检查防火墙设置

日志记录

服务器记录错误以帮助调试。检查控制台输出以获取详细的错误消息。

贡献

分叉存储库
创建要素分支
进行更改
如果适用，添加测试
提交拉取请求

许可证

此项目根据MIT许可证获得许可-有关详细信息，请参阅许可证文件。

支持

对于问题和疑问：

检查故障排除部分
查看服务器日志以了解错误详细信息
在GitHub上打开一个问题