内容
# 🗄️ SQL MCP 服务器
一个强大的 **模型上下文协议（MCP）** 服务器，允许 ChatGPT 和其他 LLM 客户端使用自然语言与 PostgreSQL 数据库交互。现在包含一个漂亮的 **Streamlit 网页界面**，用于直接数据库交互！
[](https://fastmcp.cloud)
[](https://www.python.org/downloads/)
[](https://www.postgresql.org/)
[](https://www.sqlite.org/)
[](https://streamlit.io/)
---
## ✨ 功能
- 🔍 **自然语言查询** - 用普通英语提问，获取 SQL 结果
- 🎛️ **Streamlit 网页界面** - 美观的 8 页网页界面，用于数据库探索
- 📊 **智能分页** - 使用基于会话的分页导航大型数据集
- 📊 **SQLite 支持** - 为离线开发自动创建本地 SQLite 数据库
- 🛡️ **安全第一** - SQL 注入防护， 只读查询，表白名单
- ⚡ **实时数据** - 连接到实时 PostgreSQL（支持 Neon.tech）
- 📄 **静态模式** - 无需数据库即可运行，用于演示和测试
- 🔧 **20+ MCP 工具** - 全面的数据库操作工具集
- 🤖 **AI SQL 生成器** - LLM 驱动的 SQL 生成，带有优化提示
- 🔄 **PR-Agent 集成** - 通过 GitHub Actions 实现自动化代码审查
---
## 📁 项目结构
```
sql-db-mcp/
├── main.py # 🚀 FastMCP 服务器主入口
├── app.py # 🎛️ Streamlit 网页界面
├── requirements.txt # Python 依赖项
├── Dockerfile # Docker 部署配置
├── docker-compose.yml # Docker Compose 用于本地开发
├── .env # 环境变量（从 .env.example 创建）
├── .env.example # 示例环境配置
│
├── src/ # 源代码模块
│ ├── __init__.py
│ ├── schema.py # 数据库模式定义
│ │
│ ├── tools/ # MCP 工具
│ │ ├── __init__.py
│ │ ├── database.py # 数据库连接和查询
│ │ ├── sql_generator.py # LLM 驱动的 SQL 生成
│ │ ├── session_store.py # 分页会话管理
│ │ └── sqlite_local.py # SQLite 本地数据库支持
│ │
│ ├── resources/ # MCP 资源
│ │ ├── __init__.py
│ │ └── catalog.py # 模式，示例，指南
│ │
│ └── prompts/ # MCP 提示
│ ├── __init__.py
│ └── templates.py # 查询模板
│
├── db/ # 数据库脚本
│ ├── local.db # SQLite 本地数据库（自动创建）
│ ├── setup_db.sql # 表创建和种子数据
│ └── seed_data.py # 生成大型示例数据集
│
├── .github/workflows/ # CI/CD
│ └── pr-agent.yml # PR-Agent 自动化代码审查
│
├── docs/ # 文档
│ ├── neon_setup.md # Neon.tech 设置指南
│ ├── security_audit.md # 安全审查报告
│ └── architecture.md # 系统架构
│
└── tests/ # 单元测试
└── __init__.py
```
---
## 🚀 快速开始
### 1. 克隆和安装
```bash
git clone https://github.com/pankajshakya627/sql-mcp.git
cd sql-mcp
python -m venv venv
source venv/bin/activate # Windows: venv\Scripts\activate
pip install -r requirements.txt
```
### 2. 配置环境
创建 `.env` 文件（或从 `.env.example` 复制）：
```env
# 选项 1：PostgreSQL（Neon.tech 云）
DATABASE_URL=postgresql://user:password@host/dbname?sslmode=require
STATIC_SCHEMA_MODE=false
# 选项 2：SQLite 本地数据库（自动创建 db/local.db）
DATABASE_TYPE=sqlite
# 选项 3：静态模式（无需数据库）
STATIC_SCHEMA_MODE=true
# LLM API（用于 AI SQL 生成）
OPENROUTER_API_KEY=sk-or-v1-your-key-here
# 或
OPENAI_API_KEY=sk-your-key-here
```
### 3. 运行选项
**MCP 服务器（用于 ChatGPT/Claude）：**
```bash
python main.py
```
**Streamlit 网页界面：**
```bash
streamlit run app.py
# 或使用自定义端口：
streamlit run app.py --server.port 8090
```
---
## 🎛️ Streamlit 网页界面
一个漂亮的 8 页网页界面，用于数据库探索：
| 页面 | 功能 |
| ------------------------ | ------------------------------------------------------- |
| 🏠 **仪表盘** | 快速统计，一键查询，AI 搜索，数据预览 |
| 🔍 **查询数据库** | 执行 SQL，验证语法，优化提示 |
| 🤖 **AI SQL 生成器** | 自然语言到 SQL，生成和执行 |
| 📊 **模式浏览器** | 模式概览，表详情，数据预览 |
| 📄 **分页结果** | 大查询分页导航 |
| 📈 **数据报告** | 预建的员工，部门，角色，项目报告 |
| 🛠️ **工具和实用程序** | SQL 验证器，优化提示，列出表 |
| ⚙️ **数据库状态** | 连接测试，环境信息，统计 |
### 连接模式
在界面中直接切换数据库：
- 🌐 **PostgreSQL** - 连接到 Neon.tech 或任何 PostgreSQL
- 💾 **SQLite** - 使用本地 `db/local.db`（自动创建示例数据）
- 📄 **静态** - 无需数据库的演示模式
---
## 🛠️ 可用的 MCP 工具
### 数据库查询工具
| 工具 | 描述 |
| -------------------- | ------------------------------------------------------------- |
| `ask_database` | 智能查询路由器 - 分析问题并使用最佳方法 |
| `execute_sql` | 执行原始 SQL SELECT 查询 |
| `run_query` | 执行 SQL 并格式化表输出 |
| `generate_sql_query` | 从自然语言生成 SQL（不执行） |
### 分页工具
| 工具 | 描述 |
| ----------------- | ------------------------------------------------------------- |
| `paginated_query` | 执行查询分页（20-50 行/页） |
| `next_page` | 获取下一页结果 |
| `prev_page` | 获取上一页结果 |
| `goto_page` | 跳转到特定页码 |
| `clear_session` | 清除分页会话 |
### 模式和信息工具
| 工具 | 描述 |
| ---------------- | ----------------------------------------- |
| `get_schema` | 获取完整数据库模式 |
| `get_table_info` | 获取列，类型，表行数 |
| `list_tables` | 列出所有表并获取行数 |
| `db_status` | 检查数据库连接状态 |
### 数据工具
| 工具 | 描述 |
| ------------------ | ------------------------------------------------ |
| `list_employees` | 列出员工（可选部门筛选） |
| `list_departments` | 列出所有部门 |
### 实用工具
| 工具 | 描述 |
| ----------------------- | ---------------------------------------------- |
| `validate_sql` | 验证 SQL 语法 |
| `get_optimization_tips` | 获取 LLM 驱动的查询优化建议 |
---
## 📊 SQLite 本地数据库
用于离线开发，提供本地 SQLite 数据库：
```bash
# 在 .env 中启用 SQLite
DATABASE_TYPE=sqlite
```
数据库（`db/local.db`）自动创建示例数据：
- 10 名员工
- 5 个部门
- 9 个角色
- 6 个项目
---
## 💬 使用示例
### 自然语言查询（通过 ChatGPT/Claude）
```
使用 ask_database: "工程部门有多少名员工？"
```
```
使用 ask_database: "显示薪酬最高的 5 个角色"
```
```
使用 ask_database: "哪些项目当前处于活动状态？”
```
### AI SQL 生成
```
使用 generate_sql_query: "查找 2023 年入职的所有员工及其部门"
```
**结果：
```sql
SELECT e.name, e.email, e.hire_date, d.name as department
FROM employee e
JOIN department d ON e.department_id = d.id
WHERE e.hire_date >= '2023-01-01'
ORDER BY e.hire_date DESC;
```
### 大结果分页
```
使用 paginated_query with "SELECT * FROM employee" and page_size 20
```
```
使用 next_page with session_id "abc12345"
```
```
使用 goto_page with session_id "abc12345" and page_number 3
```
### 模式探索
```
使用 get_schema
```
```
使用 get_table_info for the "employee" table
```
```
使用 list_tables
```
### 查询优化
```
使用 get_optimization_tips for "SELECT * FROM employee WHERE name LIKE '%john%'"
```
### Streamlit 网页界面
1. **启动服务器：
```bash
streamlit run app.py --server.port 8090
```
2. **在侧边栏中选择连接模式：
- 🌐 PostgreSQL (Neon.tech)
- 💾 SQLite (本地)
- 📄 静态（演示）
3. **导航页面：**
- 🏠 仪表盘 - 快速统计和操作
- 🔍 查询数据库 - 执行 SQL
- 🤖 AI 生成器 - 自然语言到 SQL
- 📊 模式浏览器 - 浏览表
- 📄 分页 - 大结果集
- 📈 报告 - 预建报告
---
## 🗃️ 数据库模式
```sql
-- department: 组织部门
CREATE TABLE department (
id SERIAL PRIMARY KEY,
name VARCHAR(100) NOT NULL,
location VARCHAR(100)
);
-- role: 具有薪资范围的工作角色
CREATE TABLE role (
id SERIAL PRIMARY KEY,
title VARCHAR(100) NOT NULL,
salary_range VARCHAR(50)
);
-- employee: 员工记录
CREATE TABLE employee (
id SERIAL PRIMARY KEY,
name VARCHAR(100) NOT NULL,
email VARCHAR(100) UNIQUE,
department_id INTEGER REFERENCES department(id),
role_id INTEGER REFERENCES role(id),
hire_date DATE DEFAULT CURRENT_DATE
);
-- project: 活动项目
CREATE TABLE project (
id SERIAL PRIMARY KEY,
name VARCHAR(100) NOT NULL,
description TEXT,
department_id INTEGER REFERENCES department(id),
status VARCHAR(20) DEFAULT 'Active'
);
```
---
## 🤖 PR-Agent 集成
通过 GitHub Actions 实现每个 PR 的自动化代码审查：
```yaml
# .github/workflows/pr-agent.yml 触发：
- pull_request: [opened, synchronize, reopened]
- workflow_dispatch: 手动触发
```
**可用操作：
- `review` - 代码审查，带有问题和建议
- `describe` - 生成 PR 标题和描述
- `improve` - 代码改进建议
- `ask` - 回答有关 PR 的问题
- `changelog` - 生成变更日志条目
- `all` - 运行所有操作
**设置：
1. 添加 `PR_AGENT_PAT` 机密，允许访问 PR-AGENT 仓库
2. 添加 API 密钥：`GROQ_API_KEY`，`OPENROUTER_API_KEY`等
---
## ☁️ 云部署
### 部署到 fastmcp.cloud
1. 推送到 GitHub
2. 在 [fastmcp.cloud](https://fastmcp.cloud) 连接仓库
3. 添加环境变量：
- `DATABASE_URL`
- `STATIC_SCHEMA_MODE=false`
- `OPENROUTER_API_KEY`
4. 部署
### 使用 Neon.tech 作为数据库
参见 [docs/neon_setup.md](docs/neon_setup.md) 获取逐步指南。
---
## 🔒 安全
- ✅ **只读查询** - 仅允许 SELECT 语句
- ✅ **SQL 注入防护** - 表白名单，输入验证
- ✅ **行限制** - 每个查询最多 50 行
- ✅ **会话超时** - 分页会话在 5 分钟后过期
- ✅ **代码中无凭证** - 所有机密均通过环境变量
参见 [docs/security_audit.md](docs/security_audit.md) 获取完整安全审查。
---
## 🐳 Docker
### 构建和运行
```bash
docker build -t sql-mcp .
docker run -p 8000:8000 \
-e DATABASE_URL="your_connection_string" \
-e STATIC_SCHEMA_MODE=false \
sql-mcp
```
### 使用 Docker Compose
```bash
docker-compose up
```
---
## 📊 架构
```mermaid
graph TB
subgraph "客户端层"
ChatGPT[ChatGPT]
Claude[Claude Desktop]
Inspector[MCP Inspector]
StreamlitUI[Streamlit 网页界面]
end
subgraph "MCP 服务器"
FastMCP[FastMCP 服务器]
Tools[20+ MCP 工具]
Resources[MCP 资源]
Sessions[会话存储]
end
subgraph "数据层"
Neon[(Neon PostgreSQL)]
SQLite[(SQLite 本地)]
Static[静态模式]
end
ChatGPT --> FastMCP
Claude --> FastMCP
Inspector --> FastMCP
StreamlitUI --> Tools
FastMCP --> Tools
FastMCP --> Resources
Tools --> Sessions
Tools --> Neon
Tools --> SQLite
Tools --> Static
```
---
## 🤝 贡献
1. 复刻仓库
2. 创建功能分支（`git checkout -b feature/amazing-feature`）
3. 提交更改（`git commit -m 'Add amazing feature'`）
4. 推送到分支（`git push origin feature/amazing-feature`）
5. 打开拉取请求
PR-Agent 将自动审查您的代码！
---
## 📝 许可证
Apache License 2.0 - 参见 [LICENSE](LICENSE) 获取详细信息。
---
## 🙏 致谢
- [FastMCP](https://fastmcp.cloud) - MCP 服务器框架
- [Neon](https://neon.tech) - 无服务器 PostgreSQL
- [Streamlit](https://streamlit.io) - 网页界面框架
- [LangChain](https://langchain.com) - LLM 流程
- [LangGraph](https://github.com/langchain-ai/langgraph) - 代理框架
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器