xugu MCP

XuguDB MCP服务器

](https://pypi.org/project/xugu-mcp/) ](https://pypi.org/project/xugu-mcp/)   

一种模型上下文协议（MCP）服务器 游戏DB (虚谷数据库) 具有完整的DDL/DML支持、多LLM提供程序集成和Chat2SQL（自然语言到SQL）功能。

特性

• 完整数据库操作：支持SELECT、INSERT、UPDATE、DELETE、CREATE、ALTER、DROP
• 图式反思：列出表，描述表结构，查看关系
• Chat2SQL：使用LLM（Claude、OpenAI、本地模型）将自然语言查询转换为SQL
• 多LLM支持：灵活的LLM提供者配置（Claude、OpenAI、zAI/Zhipu、Local/Ollama）
• 连接池：高效的数据库连接管理
• 审计日志：全面的操作日志记录以确保安全
• 查询优化：解释支持和优化建议

安装

先决条件

Python版本要求： 该项目需要 Python 3.6到3.11 （由于XuguDB驱动程序的兼容性，目前不支持Python 3.12+）。

• Python 3.6、3.7、3.8、3.9、3.10或3.11 （3.11推荐）
• XuguDB数据库实例
• （可选）用于Chat2SQL功能的LLM API密钥

如果你的Python版本不正确，请使用下面的自动设置脚本 -他们会自动为您安装和配置正确的Python版本！

快速设置（推荐）

该项目提供 自动设置脚本 这将检查和配置您的环境：

视窗

# Run the setup script
.\scripts\setup.ps1

macOS/Linux

# Make script executable (first time only)
chmod +x scripts/setup.sh

# Run the setup script
./scripts/setup.sh

安装脚本将：

• ✅ 检查是否安装了uv（如果缺少，请安装）
• ✅ 检查Python 3.11是否可用（如果缺少，请通过uv安装）
• ✅ 使用正确的Python版本创建虚拟环境
• ✅ 安装所有依赖项
• ✅ 验证安装

安装完成后：

# Activate virtual environment
# Windows:
.venv\Scripts\Activate.ps1

# macOS/Linux:
source .venv/bin/activate

# Start the MCP server
python main.py

______________________________________________________________________

Python版本管理

关键： 该项目需要 Python 3.6到3.11不支持Python 3.12+。

快速检查：

python --version  # Should be 3.6-3.11

如果你的Python版本不正确，请使用我们的自动设置：

# Option 1: After pip install - Run the setup checker
xugu-mcp-setup

# Option 2: For source installation - Run the setup script
# Windows
.\scripts\setup.ps1
# macOS/Linux
./scripts/setup.sh

这些命令将：

• ✅ 检查紫外线，必要时安装紫外线
• ✅ 自动安装Python 3.11
• ✅ 设置虚拟环境
• ✅ 安装所有依赖项

______________________________________________________________________

手动设置（高级）

如果您更喜欢手动设置，请使用以下工具之一：

更多Python版本管理帮助：

• 紫外线文件
• pyenv文档
• pyenv-win文档

选项1：从PyPI安装（推荐）

# Direct installation
pip install xugu-mcp

# Or using uv
uv pip install xugu-mcp

安装后，检查您的环境：

# One-click environment check and setup guide
xugu-mcp-setup

这 xugu-mcp-setup 命令将：

• ✅ 检查您的Python版本是否受支持（3.6-3.11）
• ✅ 如果您的环境需要设置，请提供分步说明
• ✅ 指导您安装uv和正确的Python版本

如果你的Python版本受支持，你可以直接使用：

# Stdio mode
xugu-mcp

# HTTP/SSE mode
xugu-mcp-http

选项2：从源代码安装

# Clone the repository
git clone https://github.com/xugudb/xugu-mcp.git
cd xugu-mcp

# Run the setup script (recommended)
# Windows:
.\scripts\setup.ps1
# macOS/Linux:
./scripts/setup.sh

安装脚本将：

• ✅ 检查紫外线，必要时安装紫外线
• ✅ 自动安装Python 3.11
• ✅ 创建虚拟环境
• ✅ 安装所有依赖项

______________________________________________________________________

安装完成后：

# Activate virtual environment
# Windows:
.venv\Scripts\Activate.ps1
# macOS/Linux:
source .venv/bin/activate

# Start the MCP server
uv run xugu-mcp

源安装的Claude桌面配置：

{
  "mcpServers": {
    "xugu": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "E:\\workspace\\xugu-mcp\\xugu-mcp",
        "xugu-mcp"
      ],
      "env": {
        "XUGU_DB_HOST": "your_database_host",
        "XUGU_DB_PORT": "5138",
        "XUGU_DB_DATABASE": "SYSTEM",
        "XUGU_DB_USER": "SYSDBA",
        "XUGU_DB_PASSWORD": "your_password"
      }
    }
  }
}

注： 更新 --directory 您实际项目位置的路径。

配置

环境变量

复制 .env.example 到 .env 并配置：

cp .env.example .env

关键配置：

# Database
XUGU_DB_HOST=localhost
XUGU_DB_PORT=5138
XUGU_DB_DATABASE=SYSTEM
XUGU_DB_USER=SYSDBA
XUGU_DB_PASSWORD=your_password

# LLM (for Chat2SQL)
CHAT2SQL_MODE=lightweight  # 'lightweight' (default, no API key) or 'standalone' (requires API key)
LLM_PROVIDER=claude  # or openai, zai, zhipu, local, ollama
LLM_MODEL=claude-3-5-sonnet-20241022
LLM_API_KEY=your_api_key  # Only required for standalone mode
LLM_BASE_URL=  # Optional custom API URL
LLM_TEMPERATURE=0.0
LLM_MAX_TOKENS=4096

配置文件

您还可以使用 config/config.yaml 用于配置（由env变量覆盖）。

LLM提供商

服务器支持Chat2SQL功能的多个LLM提供程序：

供应商特定注意事项：

• zAI/齐普：API基本URL默认为 https://open.bigmodel.cn/api/paas/v4/
• 当地/Ollama：预计Ollama会跑 http://localhost:11434/v1/

Chat2SQL模式：

轻量级模式（默认）

• 不需要LLM API密钥
• MCP提供模式上下文和SQL验证
• 您现有的LLM（Claude Desktop中的Claude等）生成SQL
• 更低的延迟，更好的上下文感知
• 集 CHAT2SQL_MODE=lightweight （或保持未设置，因为这是默认设置）

单独模式

• 需要LLM_API_KEY 待配置
• MCP使用内部LLM生成SQL
• 对于仅API访问或客户端LLM不可用时有用
• 集 CHAT2SQL_MODE=standalone 并配置 LLM_API_KEY

按模式列出的Chat2SQL要求：

一般注意事项：

• 其他数据库操作（查询、模式、DML、DDL）无需任何LLM配置即可工作
• 云提供商（claude、openai、zai、zhipu）需要 LLM_API_KEY 用于独立模式
• 本地提供商（本地、ollama）不需要API密钥，但需要运行ollama

可用型号：

• 克劳德：第3-5-联，第3-5-合，第3-opus联
• OpenAI:gpt-4o、gpt-4o-mini、gpt-4-turbo、gpt-3.5-turbo
• zAI:glm-4、glm-4-plus、glm-4-空气、glm-4-flash
• 当地：Callama3.2，Qwen2.5，Mistral，CodeCalma，Gemma

用法

运行服务器

XuguDB MCP服务器支持 两种运输方式 对于不同的用例：

______________________________________________________________________

模式1：标准模式（本地开发）

最适合： 本地开发，Claude Desktop集成

运输： 标准输入/输出（stdio）

启动命令：

# Using PyPI installed version (recommended)
xugu-mcp

# Or with uv (source installation)
uv run xugu-mcp

# Or directly with Python
python -m xugu_mcp.main

它是如何工作的：

• 作为本地子进程运行
• 通过stdin/stdout进行通信
• Claude Desktop用于本地MCP连接
• 无需网络端口

______________________________________________________________________

模式2:HTTP/SSE模式（远程/网络）

最适合： 远程服务器、网络访问、多个客户端

运输： HTTP与服务器发送事件（SSE）

启动命令：

# Set environment variables
export XUGU_DB_HOST=your_database_host
export XUGU_DB_PORT=5138
export XUGU_DB_DATABASE=SYSTEM
export XUGU_DB_USER=SYSDBA
export XUGU_DB_PASSWORD=your_password

# Optional: Configure HTTP server
export HTTP_SERVER_HOST=0.0.0.0    # Listen on all interfaces
export HTTP_SERVER_PORT=8000       # HTTP port

# Start HTTP server (PyPI installed version)
xugu-mcp-http

# Or with uv (source installation)
uv run xugu-mcp-http

# Or directly with Python
python -m xugu_mcp.http_server

HTTP服务器将在以下时间启动： http://0.0.0.0:8000 （默认）

HTTP端点：

• SSE连接： http://your-host:8000/sse -服务器发送流媒体事件
• 邮件POST： http://your-host:8000/messages/ -客户端消息端点

HTTP服务器配置选项：

# Server binding
HTTP_SERVER_HOST=0.0.0.0          # 0.0.0.0 for all interfaces, 127.0.0.1 for local only
HTTP_SERVER_PORT=8000             # HTTP port number

# Security (optional)
HTTP_SERVER_ENABLE_CORS=false     # Enable CORS for web clients
HTTP_SERVER_ENABLE_AUTH=false     # Enable authentication
HTTP_SERVER_AUTH_TOKEN=token      # Authentication token

# Endpoints (usually no need to change)
HTTP_SERVER_SSE_ENDPOINT=/sse     # SSE connection endpoint
HTTP_SERVER_MESSAGE_ENDPOINT=/messages/  # Message POST endpoint

______________________________________________________________________

模式比较

______________________________________________________________________

Claude桌面配置

配置位置：

• macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
• 窗户： %APPDATA%\Claude\claude_desktop_config.json

标准模式（本地-推荐）

{
  "mcpServers": {
    "xugu": {
      "command": "xugu-mcp",
      "env": {
        "XUGU_DB_HOST": "your_database_host",
        "XUGU_DB_PORT": "5138",
        "XUGU_DB_DATABASE": "SYSTEM",
        "XUGU_DB_USER": "SYSDBA",
        "XUGU_DB_PASSWORD": "your_password"
      }
    }
  }
}

用于源安装，更改 "command": "xugu-mcp" 致：

"command": "uv",
"args": ["run", "--directory", "/path/to/xugu-mcp", "xugu-mcp"]

HTTP/SSE模式（远程/网络）

{
  "mcpServers": {
    "xugu": {
      "url": "http://127.0.0.1:8000/sse",
      "transport": "sse"
    }
  }
}

注： 在启动Claude Desktop之前启动HTTP服务器：

XUGU_DB_HOST=your_host XUGU_DB_PASSWORD=your_password xugu-mcp-http

两种模式

{
  "mcpServers": {
    "xugu-local": {
      "command": "xugu-mcp",
      "env": {
        "XUGU_DB_HOST": "your_database_host",
        "XUGU_DB_PORT": "5138",
        "XUGU_DB_DATABASE": "SYSTEM",
        "XUGU_DB_USER": "SYSDBA",
        "XUGU_DB_PASSWORD": "your_password"
      }
    },
    "xugu-remote": {
      "url": "http://127.0.0.1:8000/sse",
      "transport": "sse"
    }
  }
}

______________________________________________________________________

快速入门示例

地方发展（Stdio）

# Install
pip install xugu-mcp

# Check environment
xugu-mcp-setup

# Start server
xugu-mcp

# For source installation, use: uv run xugu-mcp

远程服务器（HTTP/SSE）

# Set environment variables
export XUGU_DB_HOST=your_host
export XUGU_DB_PASSWORD=your_password
export HTTP_SERVER_PORT=8000

# Start HTTP server
xugu-mcp-http

# Test endpoint
curl http://localhost:8000/sse

# For source installation, use: uv run xugu-mcp-http

测试与验证

验证安装

# Check if installation was successful
xugu-mcp --help  # or
xugu-mcp-http --help

# Check version
pip show xugu-mcp

测试数据库连接

# Test using environment variables
export XUGU_DB_HOST=your_database_host
export XUGU_DB_PORT=5138
export XUGU_DB_DATABASE=SYSTEM
export XUGU_DB_USER=SYSDBA
export XUGU_DB_PASSWORD=your_password

# Stdio mode test (should start and wait for MCP messages)
xugu-mcp

# HTTP mode test
xugu-mcp-http

# In another terminal, test HTTP endpoint
curl http://localhost:8000/sse

在Claude Desktop中进行测试

1. 配置Claude Desktop（见上面的配置示例）
2. 重新启动克劳德桌面
3. 尝试克劳德对话：

- “列出所有表” - “显示表结构” - “执行SELECT查询”

故障排除

Python版本问题

问题：Python版本为3.12+或不在3.6-3.11范围内

这是最常见的问题！XuguDB驱动程序（xgcondb）仅支持Python 3.6-3.11。

快速解决方案：

# Option 1: After pip install
xugu-mcp-setup

# Option 2: For source installation
./scripts/setup.sh  # or .\scripts\setup.ps1 on Windows

有关手动设置选项，请参阅 Python版本管理 上面。

______________________________________________________________________

安装问题

问题： pip install xugu-mcp 失败

# Try upgrading pip
pip install --upgrade pip

# Use uv for installation (faster and more reliable)
pip install uv
uv pip install xugu-mcp

# Or install from source
git clone https://github.com/xugudb/xugu-mcp.git
cd xugu-mcp
uv sync

问题：命令 xugu-mcp 未找到

# Check if Python scripts path is in PATH
python -m site --user-base

# Add to PATH (macOS/Linux)
export PATH="$HOME/.local/bin:$PATH"

# Or use full path
python -m xugu_mcp.main

# Or use uv to run
uv run xugu-mcp

连接问题

问题：无法连接到数据库

# Check if database is reachable
telnet your_database_host 5138

# Check firewall settings
# Ensure XuguDB service is running

# Verify credentials
export XUGU_DB_HOST=your_database_host
export XUGU_DB_PORT=5138
export XUGU_DB_DATABASE=SYSTEM
export XUGU_DB_USER=SYSDBA
export XUGU_DB_PASSWORD=your_password

问题：Claude Desktop无法连接到MCP服务器

# Check stdio mode
xugu-mcp

# Check Claude Desktop logs
# macOS: ~/Library/Logs/Claude/
# Windows: %APPDATA%\Claude\logs

# Verify config file path
# macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

端口已在使用中

# Find and kill process using port 8000
lsof -ti:8000 | xargs kill -9

# Or use a different port
export HTTP_SERVER_PORT=8001
xugu-mcp-http

连接被拒绝

# Check if HTTP server is running
curl http://localhost:8000/sse

# Check server logs for errors
# Make sure XUGU_DB_* variables are set correctly

标准模式无响应

# Verify the command works
xugu-mcp

# Check Python version (requires 3.11+)
python --version

# Reinstall if needed
pip install --force-reinstall xugu-mcp

# Or reinstall from source
git clone https://github.com/xugudb/xugu-mcp.git
cd xugu-mcp
uv sync

获取帮助

如果问题仍然存在，请：

1. 检查
2. 通过以下方式提交新问题：

- 操作系统版本 - Python版本 - 错误消息 - 配置文件内容（删除敏感信息）

MCP工具

查询执行

图式反思

DML操作

DDL操作

Chat2SQL操作

Chat2SQL支持两种模式：

轻量级模式（默认）

• 不需要LLM API密钥 -使用您现有的LLM（Claude桌面中的Claude等）
• MCP仅提供模式上下文和验证
• 更低的延迟，更好的上下文感知

单独模式

• 需要LLM_API_KEY -MCP使用内部LLM生成SQL
• 对API专用访问很有用

安全与审计

行政与管理

数据库信息

MCP资源

开发状态

完成✅

• 第一阶段：基础框架

- 包含所有目录的项目结构 - 使用Pydantic进行配置管理 - 具有事务的数据库连接管理器 - 日志记录和错误处理实用程序 - 带查询工具的基本MCP服务器

• 第2阶段：查询工具和模式自省

- 13个MCP工具（查询、模式、数据库信息） - 8个MCP资源（表、关系、索引、视图、元数据） - 模式探索工具（索引、外键、视图）

• 第三期：DML操作

- 6个DML工具（插入、更新、删除、追加、截断、bulk_import） - 单行和批处理操作 - 参数化WHERE子句支持 - 大数据集的批处理

• 阶段4：DDL操作

- 8个DDL工具（create_table、drop_table、alter_table、create_index、drop_index、create_view、drop_view、backup_table） - 表和索引管理 - 视图创建和管理 - 表备份功能

• 阶段5：LLM集成

- 4家法学硕士提供者（克劳德、OpenAI、zAI/智普、Local/Ollama） - LLM基础接口和提供者工厂 - 支持流式响应 - 每个提供商的多模型支持

• 第6阶段：Chat2SQL引擎

- 9个Chat2SQL工具（NL到SQL、解释、验证、优化、修复） - 具有智能缓存的模式管理器 - 带安全检查的SQL验证器 - SQL防注入消毒剂 - 快速构建者，很少学习

• 第7阶段：安全与审计

- 7安全和审计工具（审计日志、统计数据、角色、权限） - 所有操作的全面审计日志记录 - 滑动窗口和令牌桶的速率限制 - 基于角色的访问控制（5个预定义角色） - 查询执行钩子（前/后/错误） - 每客户费率限制 - 查询跟踪缓慢

• 第8阶段：生产准备就绪

- 9个管理工具（健康检查、指标、诊断） - 系统指标收集（CPU、内存、磁盘使用率） - 数据库连接池监控 - 从审核日志中查询历史检索 - 缓存管理 - 连接诊断 - 服务器信息检索

进行中🚧

计划的📋

HTTP部署

生产部署

对于生产部署，建议使用：

1. 反向代理：使用Nginx或Traefik作为反向代理
2. 流程经理：使用systemd、supervisor或PM2
3. SSL/TLS：启用HTTPS以进行安全通信

Nginx配置示例

upstream xugu_mcp {
    server localhost:8000;
}

server {
    listen 443 ssl;
    server_name your-domain.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location /sse {
        proxy_pass http://xugu_mcp;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_buffering off;
        proxy_cache off;
        proxy_set_header Connection '';
        proxy_http_version 1.1;
        chunked_transfer_encoding off;
    }

    location /messages/ {
        proxy_pass http://xugu_mcp;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

系统服务示例

[Unit]
Description=XuguDB MCP HTTP Server
After=network.target

[Service]
Type=simple
User=xugu
WorkingDirectory=/path/to/xugu-mcp
Environment="PATH=/path/to/uv/.local/bin"
ExecStart=/path/to/uv/.local/bin/uv run xugu-mcp-http
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

Docker部署

创建一个 Dockerfile:

FROM python:3.11-slim

WORKDIR /app

COPY . .

RUN pip install --no-cache-dir uv && \
    uv pip install --system -e .

ENV HTTP_SERVER_HOST=0.0.0.0
ENV HTTP_SERVER_PORT=8000

EXPOSE 8000

CMD ["uv", "run", "xugu-mcp-http"]

构建并运行：

docker build -t xugu-mcp .
docker run -d -p 8000:8000 --env-file .env xugu-mcp

监控

HTTP服务器公开了几个端点进行监控：

• 健康检查：使用 health_check 工具
• 指标：使用 get_server_metrics 工具
• 审计日志：使用 get_audit_log 工具

使用curl的示例：

# Health check (if you add a dedicated HTTP endpoint)
curl http://your-host:8000/health

# Get server metrics via MCP tool
# (This requires an MCP client)

发展

项目结构

xugu-mcp/
├── src/xugu_mcp/
│   ├── main.py              # MCP server entry point (stdio mode)
│   ├── http_server.py       # MCP server entry point (HTTP/SSE mode)
│   ├── config/              # Configuration management
│   ├── db/                  # Database connection & operations
│   ├── llm/                 # LLM provider implementations
│   ├── chat2sql/            # Chat2SQL engine
│   ├── mcp_tools/           # MCP tool implementations
│   ├── mcp_resources/       # MCP resource implementations
│   ├── security/            # Security & audit
│   └── utils/               # Utilities
├── config/                  # Configuration files
├── tests/                   # Test suite
└── pyproject.toml           # Project configuration

运行测试

uv run pytest

代码质量

# Format code
uv run black src/

# Lint
uv run ruff check src/

# Type check
uv run mypy src/

安全

• SQL注入防护：参数化查询和输入验证
• 审计日志：记录所有数据库操作
• 速率限制：可配置的查询速率限制
• 连接安全性：数据库连接的SSL/TLS支持

许可证

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

贡献

欢迎投稿！请打开问题或提交拉取请求。

参考文献

• XuguDB Python文档
• 模型上下文协议