内容
align="center">
# 文本转 SQL MCP
MCP（模型上下文协议）服务器，连接任意 LLM 客户端到 PostgreSQL 数据库。主机 LLM 使用公开的模式生成 SQL 查询并执行它们。
[](https://www.python.org/downloads/)
[](https://www.postgresql.org/)
[](https://github.com/MagicStack/asyncpg)
[](https://docs.pydantic.dev/)
[](https://docs.docker.com/compose/)
[](https://modelcontextprotocol.io/)
[](https://github.com/astraluv)
</div>
<div align="center">
<p><em>查看用户如何通过简单地向 LLM 提问来与数据库交互</em></p>
</div>
## 📋 目录
- [📖 概述](#-概述)
- [✨ 功能](#-功能)
- [🚀 安装](#-安装)
- [💻 使用](#-使用)
- [⚙️ 配置](#️-配置)
- [🛠️ 开发](#️-开发)
- [📁 项目结构](#-项目结构)
- [🏗️ 技术栈](#️-技术栈)
- [🔧 故障排除](#-故障排除)
- [贡献](#-贡献)
## 📖 概述
该在大型语言模型（Claude、GPT 等）和 PostgreSQL 数据库之间提供了一个安全的桥梁，使自然语言能够转换为 SQL 查询并执行。
### 💡 灵感来源
源于无数次输入 SELECT \* FROM users WHERE...，我意识到我花更多时间在编写 SQL 查询上，而不是实际。为什么不 LLM 关于你的数据库？
是一种强大的技能，但它往往是**快速数据探索的瓶颈**。我构建了这个项目，以消除“思维上下文切换”的摩擦，那些时刻会表模式或纠结于时间戳语法，以获取简单的答案。
通过利用 LLM 处理样板 SQL，你可以专注于要问的问题，而不是询问所需的语法。
### MCP 工具
| 工具 | 描述 |
| ----------------- | ----------------------------------------------- |
| `get_schema` | 返回所有表、列、类型和外键 |
| `get_sample_data` | 返回指定表的样本行 |
| `execute_query` | 执行 SQL 并返回结果（只读） |
## ✨ 功能
- **模式检查**：检索完整的数据库模式，包括表、列、类型和外键
- **样本数据**：从任何表中获取样本行以了解数据- **查询执行**：使用内置安全验证执行 SQL 查询
- **只读模式**：可配置的只读模式以防止数据修改
- **查询验证**：自动验证以防止危险操作
- **行限制**：可配置的最大行数以防止响应过大
### 安全功能
- **查询验证**：阻止危险的 SQL 操作（只读模式下的 DROP、DELETE 等）
- **函数阻止**：防止执行危险的 PostgreSQL 函数
- **防止多语句**：仅允许单个 SQL 语句
- **只读模式**：可配置为仅限于 SELECT 查询
- **行限制**：防止用过多数据淹没响应
## 🚀 安装
### 前置条件
- [uv](https://github.com/astral-sh/uv) - 快速的 Python 包管理器
- Docker 和 Docker Compose（用于 PostgreSQL 数据库）
### 快速开始
```bash
# 重置数据库并使用样本数据重新开始
make fresh
# 查看可用命令
make help
# 测试连接
make check-connection
# 查看数据库模式
make check-schema
```
### 安装 uv
```bash
# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# 或使用 Homebrew
brew install uv
```
### 设置项目
```bash
# 安装依赖项
make install
# 或
uv sync
# 使用样本数据启动本地数据库
make fresh
```
## 💻 使用
### 本地开发
```bash
# 启动本地数据库
make up-db
# 运行 MCP 服务器
uv run text_to_sql_mcp.server
```
### Claude 桌面集成
1. **启动数据库：**
```bash
make up-db
```
2. **添加到 Claude 桌面配置**（`~/ Support/Claude/claude_desktop_config.json`）：
```json
{
"mcpServers": {
"text-to-sql": {
"command": "uv",
"args": [
"--directory",
"/path/to/the/project/text-to-SQL-mcp",
"run",
"text-to-sql-mcp"
],
"env": {
"DATABASE_URL": "url/to/your/postgres/database"
}
}
}
}
```
3. **重启 Claude 桌面**并开始查询你的数据库！
### Docker 命令（仅限数据库）
```bash
# 启动数据库
make up-db
# 停止数据库
make down
# 重置数据库并重新开始
make fresh
# 查看数据库日志
make logs-db
```
### 测试数据库
当你运行 `make fresh`自动创建一个 PostgreSQL 数据库，并填充样本电子商务数据。
#### 样本数据库模式
| 表 | 描述 | 行| ------------- | ------------------------------------- | --------- |
| `users` 客户账户 | 10 |
| `categories | 产品类别 | |
| `products` 带有价格和库存的产品目录 | 16 |
| `orders` | 客户订单与状态 | 10 |
| `order_items` | 每个订单中的单个项目 | 20 |
| `reviews` | 带有评分（1-5）的产品评论 | |
**有用的视图：**
- `order_summary` - 带有客户信息和商品数量的订单
- `atings` - 带有平均评分和评论数量的产品
#### 重置测试数据库
```bash
make fresh
# 或
make reset
make up-db
```
### 测试命令
# 测试数据库连接
make check-connection
# 查看数据库模式
make check-schema
# 运行测试查询
make query QUERY="SELECT * FROM users LIMIT 5"
```
## ⚙️ 配置
该项目使用 **Pydantic 设置** 进行配置管理。
为环境变量创建 `.env` 文件：
```bash
# 必需
DATABASE_URL=postgresql://testuser:testpass@localhost:5433/testdb
# 可选
QUERY_TIMEOUT=30 # 查询超时（秒）
MAX_ROWS0 # 返回的最大行数
READ_ONLY=true # 仅限 SELECT 查询
```
**注意：** 使用 `localhost:5433` 从本地 MCP 服务器连接 Docker PostgreSQL 数据库。
## 🛠️ 开发
### 设置
```bash
# 安装开发依赖项
make install-dev
# 或
uv sync --all-extras
```
### 代码质量
```bash
# 格式化代码
make format
# 或
uv run black src/
# 检查代码
make lint
# 或
uv run ruff check src/
```
### 清理
```bash
# 清理容器、卷和 Python 缓存
make clean
```
## 📁 项目结构
```
text-to-sql/
│
├── src/
│ └── text_to_sql_mcp/
│ ├── __init__.py
│ ├── server.py # MCP 服务器入口点
│ │
│ ├── tools/
│ │ ├── __init__.py
│ │ ├── schema.py # get_schema, get_sample_data
│ │ └── query.py # execute_query
│ │
│ ├── core/
│ │ ├── __init__.py
│ │ ├── database.py # Postgres 连接
│ │ └── security.py # 查询验证
│ │
│ ├── config.py # Pydantic 设置
│ └── __init__.py
│
├── scripts/
│ ├── check_connection.py # 测试数据库连接
│ ├── check_schema.py # 将模式打印到控制台
│ └── check_query.py # 运行测试查询
│
├── docker-compose.yml # PostgreSQL 数据库设置
├── init.sql # 样本数据库初始化
├── Makefile # 常用命令
├── pyproject.toml
├── README.md
├── .env.example
└── LICENSE
```
## 🏗️ 技术栈
### 核心
- **语言**：Python 3.11+
- **包管理器**：`uv`（Astral）
- **MCP 协议**：`mcp`（官方 SDK）
- **数据库驱动**：`asyncpg`
- **验证**：`pydantic` v2
- **配置**：`pydantic-settings`
### 基础设施
- **数据库**：PostgreSQL 15（Alpine）
- **容器编排**：Docker Compose
### 开发工具
- **格式化工具**：`black`
- **检查工具**：`ruff`
- **类型检查器**：`mypy`
## 🔧 故障排除
### 连接问题
1. **检查 DATABASE_URL 格式：**
```
postgresql://testuser:testpass@localhost:5433/testdb
```
2. **确保数据库正在运行：**
```bash
make up-db
make logs-db # 检查错误
```
3. **测试连接：**
```bash
make check-connection
```
4. **验证端口映射：**
```bash
docker ps # 应该0.0.0.0:5433->/tcp
```
**从 Claude 桌面查看 MCP 日志**
```bash
tail -n 20 -F ~/Library/Logs/Claude/mcp\*.log
```
### 查询验证错误
如果查询被阻止：
1. 检查是否设置了 `READ_ONLY=true`（仅允许 SELECT 查询）
2. 验证查询是否不使用危险函数
3. 确保只执行单个 SQL 语句
性能问题
为长时间运行的查询调整 `QUERY_TIMEOUT`
2 `MAX_ROWS如果响应太大）
3. 在数据库表中添加
### 附加资源
有关更多调试帮助，请 [官方 MCP 调试文档](https://modelcontextprotocol.io/legacy/tools/debugging)。
## 🤝 贡献
欢迎贡献！请随时提交拉取请求。
