UXDB MCP Server 安装使用指南

UXDB MCP Server 是一个基于 Model Context Protocol (MCP) 的数据库管理服务。安装并启动后，AI 助手（如 Claude Desktop、Claude Code 等 MCP 客户端）即可通过自然语言查询和管理 UXDB 数据库。

本文档面向使用安装包的用户。数据库驱动已内置在安装包中，无需单独安装。

1. 安装前准备

请确认以下条件：

Python 3.12（安装包为 Python 3.12 / Linux x86_64 构建）
可用的 UXDB 数据库地址、端口、数据库名、用户名和密码
支持常用 MCP 的客户端 1、IDE 与代码编辑器 Cursor、 Windsurf、Zed、VS Code 2、IDE 插件 / 编程助手 Cline、Roo Code、Continue、GitHub Copilot 3、桌面 / 聊天客户端 Claude Desktop、LibreChat、ChatGPT 4、命令行工具 Claude Code、Gemini CLI、Qwen CLI、Goose 5、AI 工作流与 Agent 框架 WorkBuddy、Dify、n8n、Flowise、OpenClaw 6、开发平台 Microsoft Foundry
安装包文件：uxdb_mcp_server-*.whl

检查 Python 版本：

python --version
# 应显示 Python 3.12.x

如果系统有多个 Python 版本，请使用 python3.12 执行后续命令。

2. 安装

在安装包所在目录执行：

python -m pip install uxdb_mcp_server-*.whl

说明：

数据库驱动 pycouxdb 已随安装包一同安装，无需再安装
安装过程需要从 pip 源下载 mcp、pydantic、fastapi 等依赖；无法访问公网时，请使用公司内部镜像源，例如：
```
python -m pip install uxdb_mcp_server-*.whl -i http://<内部镜像源>/simple/
```
如提示 is not a supported wheel on this platform，说明当前 Python 版本或操作系统与安装包不匹配，请联系提供方获取对应平台的安装包

安装完成后验证：

uxdb-mcp-server --version

正常输出：

UXDB MCP Server version 1.1.0

升级与卸载

# 升级（重新安装新的安装包）
python -m pip install --force-reinstall uxdb_mcp_server-*.whl

# 卸载
python -m pip uninstall uxdb-mcp-server

3. 准备数据库连接信息

连接字符串格式：

uxdb://用户名:密码@主机:端口/数据库名

示例：

uxdb://uxdb:password@127.0.0.1:52025/uxdb

UXDB 默认端口为 52025。如果密码中包含 @、:、/ 等特殊字符，需要进行 URL 编码。

连接信息可通过以下任一方式提供（优先级从高到低）：

工具调用参数中的 connectionString
启动参数 --connection-string
环境变量 UXDB_CONNECTION_STRING

4. 启动服务

方式一：stdio（本地客户端推荐）

适用于 Claude Desktop、Claude Code 等在本机启动服务的客户端：

uxdb-mcp-server --connection-string "uxdb://uxdb:password@127.0.0.1:52025/uxdb"

注意：stdio 模式启动后会等待客户端通信，不会在终端输出交互界面。通常由 MCP 客户端自动拉起，无需手动执行。

方式二：Streamable HTTP（远程/多客户端推荐）

uxdb-mcp-server \
  --transport streamable_http \
  --host 127.0.0.1 \
  --port 8081 \
  --connection-string "uxdb://uxdb:password@127.0.0.1:52025/uxdb" \
  --auth-token "mytoken"

MCP 端点：http://127.0.0.1:8081/mcp
健康检查：http://127.0.0.1:8081/health
认证请求头：Authorization: Bearer mytoken

健康检查示例：

curl http://127.0.0.1:8081/health

方式三：SSE（仅用于旧版客户端）

uxdb-mcp-server --transport sse --port 8081

SSE 端点：http://127.0.0.1:8081/sse
消息端点：http://127.0.0.1:8081/messages

常用启动参数

参数	说明	默认值
`--connection-string`, `-cs`	数据库连接字符串	-
`--transport`, `-t`	传输方式：`stdio`、`streamable_http`、`sse`	`stdio`
`--host`	HTTP 绑定地址	`127.0.0.1`
`--port`, `-p`	HTTP 绑定端口	`8080`
`--path`	Streamable HTTP 的 MCP 端点路径	`/mcp`
`--auth-token`	HTTP 认证令牌	-
`--log-level`	日志级别：`DEBUG`、`INFO`、`WARNING`、`ERROR`	`INFO`
`--version`	显示版本并退出	-

查看完整帮助：

uxdb-mcp-server --help

5. 客户端接入

Claude Desktop

编辑 Claude Desktop 配置文件，添加：

{
  "mcpServers": {
    "uxdb-mcp": {
      "command": "uxdb-mcp-server",
      "args": [
        "--connection-string",
        "uxdb://uxdb:password@127.0.0.1:52025/uxdb"
      ]
    }
  }
}

Claude Code

claude mcp add uxdb -- uxdb-mcp-server \
  --connection-string "uxdb://uxdb:password@127.0.0.1:52025/uxdb"

HTTP 客户端

连接 Streamable HTTP 服务时，请求需携带 MCP 协议请求头。示例：

curl -X POST http://127.0.0.1:8081/mcp \
  -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: 2026-07-28" \
  -H "Mcp-Method: tools/list" \
  -H "Authorization: Bearer mytoken" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list",
    "params": {
      "_meta": {
        "io.modelcontextprotocol/protocolVersion": "2026-07-28",
        "io.modelcontextprotocol/clientCapabilities": {}
      }
    }
  }'

6. 环境变量

除命令行参数外，也可以通过环境变量配置：

变量	说明	默认值
`UXDB_CONNECTION_STRING`	数据库连接字符串	-
`UXDB_AUTH_TOKEN`	HTTP 认证令牌	-
`SERVER_TRANSPORT`	传输方式	`stdio`
`SERVER_HOST`	HTTP 绑定地址	`127.0.0.1`
`SERVER_PORT`	HTTP 绑定端口	`8080`
`SERVER_LOG_LEVEL`	日志级别	`INFO`
`SERVER_ENABLE_CORS`	是否启用 CORS	`true`

示例：

export UXDB_CONNECTION_STRING="uxdb://uxdb:password@127.0.0.1:52025/uxdb"
uxdb-mcp-server --transport streamable_http --port 8081

7. 可用工具

连接成功后，AI 助手可以调用以下 15 个工具：

工具名	用途
`ux_manage_schema`	模式/表管理：查看、创建、修改、删除表，管理枚举
`ux_execute_query`	执行 SELECT 查询，支持分页、count、exists
`ux_execute_mutation`	执行 INSERT/UPDATE/DELETE/UPSERT
`ux_execute_sql`	执行任意 SQL
`ux_manage_query`	查询分析：EXPLAIN、性能诊断
`ux_manage_functions`	函数及行级安全 (RLS) 管理
`ux_manage_triggers`	触发器管理
`ux_manage_indexes`	索引管理
`ux_manage_users`	用户与权限管理
`ux_manage_constraints`	约束管理
`ux_manage_comments`	对象注释管理
`ux_analyze_database`	数据库配置与性能分析
`ux_debug_database`	常见问题诊断（连接、锁、性能等）
`ux_monitor_database`	实时监控：指标、表统计、查询、锁、复制状态
`ux_manage_data_migration`	数据迁移：导入/导出

8. 常见问题

提示 uxdb-mcp-server: command not found

确认安装成功，且 Python 的脚本目录在 PATH 中。也可以使用模块方式启动：

python -m uxdb_mcp_server --connection-string "uxdb://..."

提示 No connection string provided

未提供连接字符串。请通过启动参数 --connection-string、环境变量 UXDB_CONNECTION_STRING 或工具参数 connectionString 提供。

提示认证失败或 HTTP 401

服务端启用了 --auth-token，客户端请求需携带请求头：

Authorization: Bearer <令牌>

提示连接被拒绝或连接超时

请检查：

UXDB 服务是否已启动
主机和端口是否正确（默认端口 52025）
网络、防火墙或安全组是否允许访问
用户名、密码、数据库名是否正确

安装时提示 is not a supported wheel on this platform

安装包与当前 Python/操作系统不匹配。请确认使用 Python 3.12，并联系提供方获取对应平台的安装包。

健康检查返回 degraded

服务已启动，但无法连接数据库。请检查连接字符串及 UXDB 实例状态。

需要查看详细日志

启动时添加 --log-level DEBUG，日志输出到标准错误（stderr）。