企业官网建设流程全解析

如何把 ShardingSphere-MCP 接入 Claude Code 并验证 MCP 工具调用成功

【免费下载链接】shardingsphereEmpowering Data Intelligence with Distributed SQL for Sharding, Scalability, and Security Across All Databases.项目地址: https://gitcode.com/GitHub_Trending/sh/shardingsphere

如果你的目标是在 Claude Code 里直接完成"查看逻辑库中的表、查看表结构、执行受控只读查询"这类数据库任务，就需要把 ShardingSphere-MCP 配置成 Claude Code 的 MCP Server，并确认工具调用真正返回了数据库结果。ShardingSphere-MCP 是 Apache ShardingSphere 提供的 MCP Server，用于把数据库元数据访问、受控 SQL 查询和数据库治理能力暴露给支持 MCP 的 AI 客户端。本文覆盖两种接入方式：接入已经独立启动的 HTTP Server（推荐主路径），以及由 Claude Code 在本地拉起 STDIO 进程。前置条件是：

• JAVA_HOME或PATH中可用的 JDK 21；
• 一个可通过 JDBC 访问的 ShardingSphere-Proxy 逻辑库；
• Claude Code CLI 可用；
• 使用 HTTP 方式时，Claude Code 所在环境可以访问http://127.0.0.1:18088/mcp，或你实际配置的 MCP Server 地址。

准备发行包：构建并配置 ShardingSphere-MCP

在仓库根目录执行构建命令，生成 MCP 发行包：

./mvnw -pl distribution/mcp -am -DskipTests package

然后进入构建产物目录，${version}替换为构建出的发行包版本，文档示例为5.5.4-SNAPSHOT：

cd distribution/mcp/target/apache-shardingsphere-mcp-${version}

预期结果：当前目录包含bin/、conf/、lib/。如果lib/不完整，后续启动会失败，参见后文的排查说明。

编辑conf/mcp-http.yaml，把runtimeDatabases指向已有的 ShardingSphere-Proxy 逻辑库：

runtimeDatabases: "logic_db": jdbcUrl: "jdbc:mysql://127.0.0.1:3307/logic_db" username: "root" password: "" driverClassName: "com.mysql.cj.jdbc.Driver"

其中logic_db是你在自然语言任务中引用的数据库名称。根据你实际部署的 ShardingSphere-Proxy 调整库名、地址127.0.0.1、端口3307、用户root和空密码这几个示例值。MCP Server 会从jdbcUrl解析数据库类型，username和driverClassName是必填项，无密码账号可以省略password或写""。如果目标数据库驱动没有随发行包提供，启动前把对应 JDBC 驱动 jar 放入plugins/。

启动 HTTP MCP Server

Unix-like 系统：

bin/start.sh > logs/mcp-http.log 2>&1 &

Windows：

start "ShardingSphere MCP" cmd /c "bin\start.bat > logs\mcp-http.log 2>&1"

默认配置文件是conf/mcp-http.yaml，默认端点是http://127.0.0.1:18088/mcp。启动失败时查看启动终端和logs/mcp.log，确认 Java 21 及以上版本、配置文件存在且发行包lib/目录完整。

在 Claude Code 中添加 MCP Server

确认 ShardingSphere-MCP 已经在http://127.0.0.1:18088/mcp上运行后，执行：

claude mcp add --transport http shardingsphere http://127.0.0.1:18088/mcp

如果你的 MCP Server 部署在其他地址，把 URL 换成实际配置的地址。如果希望当前用户的所有 Claude Code 项目都能使用该 MCP Server，可以使用用户级配置：

claude mcp add --transport http --scope user shardingsphere http://127.0.0.1:18088/mcp

另一种等价的可选做法是在项目根目录创建.mcp.json：

{ "mcpServers": { "shardingsphere": { "type": "http", "url": "http://127.0.0.1:18088/mcp" } } }

可选分支：由 Claude Code 拉起 STDIO 进程

如果只在本地开发环境中使用，且希望 Claude Code 在需要时自行启动 ShardingSphere-MCP 进程，可以使用 STDIO 接入：

claude mcp add --transport stdio shardingsphere -- \ /path/to/apache-shardingsphere-mcp/bin/start.sh \ /path/to/apache-shardingsphere-mcp/conf/mcp-stdio.yaml

将/path/to/apache-shardingsphere-mcp替换为实际发行包目录。STDIO 方式要求 Claude Code 能访问本地发行包和对应配置文件；每个 MCP Server 进程必须且只能选择一种传输方式，STDIO 进程不应被当作命令行交互入口手动运行。同一个shardingsphereserver name 只应对应一种接入方式；如果需要同时保留 HTTP 与 STDIO，使用不同的 server name。

验证接入和工具调用成功

验证分两步，先确认 Claude Code 识别到 Server，再确认工具调用能返回结果。

第一步，识别成功：运行claude mcp list，确认shardingsphere已出现在 MCP Server 列表中；然后在 Claude Code 中运行：

/mcp

第二步，调用成功：在 Claude Code 对话中执行一条最小验证任务，文档给出的示例包括：

• 查看logic_db中有哪些表。
• 查看orders表的列和索引。
• 对已经配置的 runtime database 执行database_gateway_validate_runtime_database。

如果工具已被列出并能返回查询结果，说明接入已经生效。进一步可用的自然语言任务（元数据查看、搜索、受控查询、规则变更预览等）以能力清单为准，见 能力清单。

常见排查项

接入后如果没有看到数据库或调用失败，按常见问题中给出的现象定位：

连接失败时 MCP 响应会返回连接错误分类，如missing_jdbc_driver（未找到配置的 JDBC 驱动）、authentication_failed、authorization_failed、connection_timeout、database_not_visible等，分类只描述失败原因，不暴露 JDBC URL、密码或堆栈信息。另外注意运行时保护：查询默认最多返回 100 行，单个 MCP 会话达到工具调用次数保护限制后会返回tool_call_limit_exceeded，此时结束当前会话并重新创建 MCP 会话即可。

涉及 SQL 执行或规则变更时，应先审查预览内容，再确认执行。完整的配置项说明（transport.http各字段、runtimeDatabases字段约束、plugins/目录等）见 配置说明；如果希望通过 Anthropic API 平台侧接入，则改用文档中的 Anthropic MCP Connector 路径，而不是本文的本地 Claude Code 接入方式。

【免费下载链接】shardingsphereEmpowering Data Intelligence with Distributed SQL for Sharding, Scalability, and Security Across All Databases.项目地址: https://gitcode.com/GitHub_Trending/sh/shardingsphere