SQL Bridge MCP

SQLBridgeMCP🚀

将任何AI安全地连接到您的SQL数据库

  

SQLBridgeMCP 是AI助手和SQL数据库之间的安全桥梁。配置一次，与任何兼容MCP的AI工具一起使用。

✨ 你能做什么？

💬 “克劳德，我们有多少活跃用户？”\ 📊 “按地区显示本月的销售额”\ 🔍 “查找上周所有超过1000美元的订单”

🎯 使用

AI工具： Claude代码•Claude API•带MCP的GPT•自定义应用程序\ 数据库： PostgreSQL•MySQL•SQLite•SQL Server\ 您的数据： 私密•安全•在您的控制之下

🚀 快速开始

1. 安装

git clone 
cd SQLBridgeMCP
python -m venv venv
source venv/bin/activate  # Linux/Mac
venv\Scripts\activate     # Windows
pip install -r requirements.txt

是什么 pip install -r requirements.txt 为什么需要它？

Python并没有预装所有东西。此项目依赖于需要下载一次才能运行的外部库。这 requirements.txt 文件只是这些库及其最低版本的列表。跑步 pip install -r requirements.txt 读取该列表并自动安装所有内容。

安装内容：

你只需要运行一次 每台机器。之后，库存储在 venv 文件夹，每次启动服务器时都可用。

2. 配置数据库 （选择一种方法）

🚀 选项A：连接字符串（更简单）

cp .env.example .env
# Edit .env with ONE line:
DB_TYPE=sqlserver
CONNECTION_STRING=Server=localhost;Database=mydb;User Id=user;Password=pass;TrustServerCertificate=true

🔧 选项B：单个变量（传统）

cp .env.example .env  
# Edit .env with separate variables:
DB_TYPE=sqlserver
DB_HOST=localhost
DB_NAME=mydb  
DB_USER=myuser
DB_PASSWORD=mypass

3. 连接到您的AI工具

选择您的AI平台并遵循特定设置：

🤖 克劳德代码

⚡ 选项A：安装脚本（推荐）

该脚本自动处理一切：创建虚拟环境、安装依赖关系，并在Claude Code中全局注册MCP服务器。

第一步： 复制示例脚本并重命名：

setup_mcp.example.bat  →  setup_mcp.bat

第二步： 打开 setup_mcp.bat 并填写您的凭据：

set "DB_HOST=your-server.database.windows.net"
set "DB_NAME=your-database-name"
set "DB_USER=your-username"
set "DB_PASSWORD=your-password"

步骤3： 双击 setup_mcp.bat --脚本将：

• 验证是否安装了Python
• 创建 venv 如果它不存在
• 从安装所有依赖项 requirements.txt
• 注册 sql-bridge 在用户范围内的Claude代码中(-s user)

步骤4： 完全重新启动Claude Code（关闭并重新打开）。

步骤5： 测试一下：

Can you check the health of my SQL database?

setup_mcp.bat 在...里 .gitignore 所以你的真实身份永远不会被认可。

______________________________________________________________________

选项B：手动CLI命令

如果您更喜欢手动设置，请先创建venv并安装依赖项：

cd SQLBridgeMCP
python -m venv venv
venv\Scripts\activate
pip install -r requirements.txt

然后在用户范围内注册MCP服务器（在所有项目中都可用）：

claude mcp add sql-bridge \
  "C:\path\to\SQLBridgeMCP\venv\Scripts\python.exe" \
  "C:\path\to\SQLBridgeMCP\main.py" \
  -s user \
  -e DB_TYPE=sqlserver \
  -e DB_HOST=your-server.database.windows.net \
  -e DB_PORT=1433 \
  -e DB_NAME=your-database \
  -e DB_USER=your-user \
  -e DB_PASSWORD=your-password

这 -s user flag为您的用户全局注册服务器(~/.claude.json)，因此它在每个项目中都可用，而不仅仅是运行命令的文件夹。

重新启动并验证：

• 完全关闭Claude代码→ 重新开放
• 测试： *“你能检查我的SQL数据库的运行状况吗？”*

🌐 API（编程）

import anthropic
from mcp_client import MCPClient

# Start MCP server
mcp = MCPClient(server_path="./main.py")

# Use with Claude API
client = anthropic.Anthropic(api_key="your-key")
message = client.messages.create(
    model="claude-3-5-sonnet-20241022",
    max_tokens=1000,
    messages=[{"role": "user", "content": "How many active employees?"}],
    tools=mcp.get_tools()  # Pass MCP tools
)

🔧 VS代码（带MCP扩展）

# Install MCP extension for VS Code
code --install-extension mcp-integration

# Add to VS Code settings.json
{
  "mcp.servers": {
    "sql-bridge": {
      "command": "python",
      "args": ["/path/to/SQLBridgeMCP/main.py"],
      "env": {
        "DB_TYPE": "sqlserver",
        "CONNECTION_STRING": "your-connection-string"
      }
    }
  }
}

🤖 其他MCP兼容客户端

对于任何MCP客户端，使用标准MCP协议：

# Start the server
python /path/to/SQLBridgeMCP/main.py

# The server exposes these MCP tools:
# - execute_sql_query
# - list_tables  
# - describe_table
# - database_health
# - list_all_databases
# - list_tables_from_database

4. 开始与您的数据聊天！

*“克劳德，给我看看收入排名前10的客户”* ✨

______________________________________________________________________

🔧 运作原理

您运行自己的服务器 → 连接到您的数据库 → 适用于任何MCP客户端

[Your AI Tool] ──► [Your SQLBridgeMCP] ──► [Your Database]
                     (Your Config)         (Your Data)

🔒 您的数据保持私密 -没有第三方，没有云服务，只有你。

🗃️ 数据库支持

🛡️ 安全

• 默认情况下为只读 -只允许SELECT查询
• SQL注入保护 -输入验证和净化
• 您的凭据 -本地存储在您的 .env 文件
• 无数据共享 -一切都在您的基础设施上运行

📖 可用的MCP工具

您的AI可以使用以下6个工具与您的数据库进行交互：

核心数据库操作

• execute_sql_query -使用参数安全执行SELECT查询

- *示例：“运行查询以查找在职员工”*

• list_tables -列出当前数据库中的所有表

- *示例：“有哪些可用的桌子？”*

• describe_table -获取详细的表模式和可选的示例数据

- *示例：“显示Users表的结构”*

数据库管理

• database_health -检查连接状态和性能指标

- *示例：“数据库连接是否正常？”*

• list_all_databases -显示SQL Server实例中的所有数据库

- *示例：“此服务器上有哪些可用的数据库？”*

• list_tables_from_database -列出特定数据库中的表

- *示例：“显示‘Analytics’数据库中的表”*

🛡️ 安全功能

• 只读访问 -只允许SELECT查询
• 输入验证 -防止SQL注入攻击
• 查询限制 -可配置的超时和行限制
• 审核日志记录 -为了安全起见，所有查询都会被记录下来

🚀 高级用法

AI使用示例

💬 自然语言示例：

*“我们有多少在职员工？”* → Uses execute_sql_query 随着 SELECT COUNT(*) FROM Employees WHERE Active = 1

*“显示数据库中的所有表”* → Uses list_tables 显示所有可用表

*“项目表的结构是什么？”* → Uses describe_table 随着 table_name="Projects"

*“我们的数据库连接是否正常工作？”* → Uses database_health 检查状态和性能

自定义应用程序

# Example: Using MCP tools programmatically
import asyncio
from mcp_client import MCPClient

async def get_employee_count():
    client = MCPClient(server_path="./main.py")
    result = await client.call_tool("execute_sql_query", {
        "query": "SELECT COUNT(*) as total FROM Employees WHERE Active = 1"
    })
    return result["data"][0]["total"]

# Get table information
async def explore_database():
    client = MCPClient(server_path="./main.py")
    
    # List all tables
    tables = await client.call_tool("list_tables")
    print(f"Found {tables['count']} tables")
    
    # Get schema for specific table
    schema = await client.call_tool("describe_table", {
        "table_name": "Employees",
        "include_sample_data": True
    })
    print(f"Employees table has {len(schema['schema'])} columns")

多个数据库

在Claude Code配置中为不同的数据库配置不同的MCP服务器。

生产部署

• 使用Docker进行容器化
• 为数据库连接配置SSL
• 设置监控和日志记录
• 创建只读数据库用户

📋 配置示例

🚀 带CONNECTION_STRING（推荐）

SQL Server（自动解析）

DB_TYPE=sqlserver
CONNECTION_STRING=Server=localhost;Database=mydb;User Id=sa;Password=MyPass123;TrustServerCertificate=true

PostgreSQL（SQLAlchemy格式）

DB_TYPE=postgresql  
CONNECTION_STRING=postgresql+psycopg://user:pass@localhost:5432/mydb

MySQL（SQLAlchemy格式）

DB_TYPE=mysql
CONNECTION_STRING=mysql+aiomysql://user:pass@localhost:3306/mydb

🔧 使用单个变量（回退）

PostgreSQL

DB_TYPE=postgresql
DB_HOST=localhost
DB_PORT=5432
DB_NAME=mydb
DB_USER=myuser
DB_PASSWORD=mypass

MySQL

DB_TYPE=mysql
DB_HOST=localhost
DB_PORT=3306
DB_NAME=mydb
DB_USER=myuser
DB_PASSWORD=mypass

SQLite（始终使用单个变量）

DB_TYPE=sqlite
DB_NAME=/path/to/database.db

📋 配置优先

1. CONNECTION_STRING （如有提供）
2. 个体变量 （DB_HOST、DB_USER等）
3. 错误 如果两者都没有配置

🛠️ 故障排除

MCP未连接？

1. 完全重新启动Claude代码 （关闭并重新打开）
2. 检查你的 claude_desktop_config.json 语法
3. 验证路径 main.py 正确（使用完整的绝对路径）
4. 确保您的 .env 文件具有正确的凭据

数据库连接问题？

1. 首先在MCP外部测试您的CONNECTION_STRING/凭据
2. 检查数据库服务器是否正在运行
3. 验证防火墙/网络对数据库的访问
4. 如果CONNECTION_STRING失败，请使用单个变量

Python/依赖关系问题？

# Verify Python and dependencies
python --version  # Should be 3.11+
pip install -r requirements.txt
python main.py  # Test server directly

常见修复：

• “无MCP图标”：完全重新启动Claude代码
• “连接失败”：检查数据库凭据
• “找不到Python”：在配置中使用python的完整路径
• “找不到模块”：运行 pip install -r requirements.txt

🆘 支持

• 🐛 问题：通过GitHub Issues报告问题
• 💬 问题：在GitHub讨论中开始讨论
• 📧 直接支持：检查存储库中的联系信息

🔗 经过测试的MCP客户端

快速设置命令：

# Easiest (Windows): copy template, fill credentials, double-click
cp setup_mcp.example.bat setup_mcp.bat
# edit setup_mcp.bat with your credentials, then run it

# Manual test (any platform)
python /path/to/SQLBridgeMCP/main.py

______________________________________________________________________

建于❤️ 对于MCP社区

*SQLBridgeMCP-人工智能和数据之间的个人桥梁*