--- title: "使用 Claude Code 接入宝塔 MCP" description: "介绍如何将宝塔 MCP 安装提示词发送给 Claude Code，完成安全确认、MCP 与 Skills 配置、连接验证和首次只读调用。" --- > Documentation Index > Fetch the complete documentation index at: https://docs.bt.cn/llms.txt > Use this file to discover all available pages before exploring further. # 使用 Claude Code 接入宝塔 MCP 将宝塔 MCP 接入 Claude Code 后，可以在 Claude Code 中查询服务器状态，并按需调用网站、数据库、Docker、安全等宝塔面板能力。 本文从**获取 MCP 安装提示词**开始介绍。尚未安装【宝塔 MCP 服务】或未完成端口、HTTPS 等准备工作的用户，请先参考[宝塔 MCP 安装指引](/ai-ops/mcp/installation)。本文截图使用 Claude Code v2.1.239，不同版本的界面、权限模式和配置行为可能略有差异。 :::warning 安全提示 安装提示词可能包含 MCP 服务地址、Token 或其他授权信息。请仅在可信项目中将提示词发送给 Claude Code，不要粘贴到公开聊天、工单或代码仓库。文中的地址、配置路径和执行结果仅为示例，请勿照抄。 ::: ## 开始前准备 开始配置前，请确认： - 【宝塔 MCP 服务】已安装并处于“运行正常”状态 - 宝塔面板防火墙和云服务器安全组已放行 MCP 服务端口 - MCP 服务已配置客户端信任且覆盖访问地址的有效 HTTPS 证书 - 已安装并登录 Claude Code - 已在 Claude Code 中打开需要使用宝塔 MCP 的项目 ## 1. 获取 MCP 安装提示词 1. 登录宝塔面板，进入【软件商店】 2. 打开【宝塔 MCP 服务】的设置页面 3. 进入【接入与体验】 4. 点击【配置 IP 白名单】，添加 Claude Code 当前使用的公网出口 IP 5. 复制页面生成的 MCP 安装提示词 ![在宝塔 MCP 服务中复制 Claude Code 安装提示词](/img/ai-ops/agent/claude-code-mcp/copy-install-prompt.png) :::tip Claude Code 所在网络的公网出口 IP 可能发生变化。如果后续出现 `403 ip denied`，请重新确认实际出口 IP，并更新 MCP 服务白名单。 ::: ## 2. 调整 Claude Code 权限模式 :::warning Auto mode 可能无法完成安装 Claude Code 的 Auto mode 可能将“修改自身 MCP 配置”“扩大工具访问范围”或“持久化配置”判定为高风险操作，因而拒绝写入配置文件。开始安装前，建议先切换到 **Manual mode（手动模式）或默认交互模式**，让 Claude Code 在关键步骤请求确认。 切换后仍需逐项核对目标项目、配置文件、MCP 地址和权限范围；不要因为改成手动模式就直接批准所有操作。安装完成后，可以再按需要切回原来的权限模式。 ::: Claude Code 界面通常可通过模式切换入口或 `Shift + Tab` 在可用权限模式之间切换，具体名称和快捷键以当前版本显示为准。 ## 3. 将安装提示词发送给 Claude Code 在 Claude Code 中打开目标项目，将刚才复制的安装提示词完整粘贴到输入框并发送。 ![将宝塔 MCP 安装提示词发送给 Claude Code](/img/ai-ops/agent/claude-code-mcp/submit-install-prompt.png) Claude Code 会下载并读取提示词指向的安装文档，识别当前客户端、项目和可用配置位置，并测试 MCP 地址的连通性。 ![Claude Code 识别项目并检查宝塔 MCP 连接地址](/img/ai-ops/agent/claude-code-mcp/inspect-installation.png) 如果安装文档同时提供内网地址和公网地址，Claude Code 应优先测试当前设备实际可达的地址。不要仅根据示例 IP 判断，应以当前网络环境的连通性测试结果为准。 :::danger 不要跳过 HTTPS 证书校验 如果安装文档或 Claude Code 建议使用 `curl -k`、关闭 TLS 校验或信任来源不明的证书，请停止执行，先为 MCP 服务配置客户端信任且覆盖访问地址的有效证书。不要通过忽略证书错误来完成接入。 ::: ## 4. 核对并批准配置写入 写入 MCP 配置属于持久化变更。Claude Code 可能提示该操作涉及修改自身配置、引入外部服务或扩大工具访问范围。 批准前至少核对以下内容： - 写入的是当前项目或预期的用户范围 - MCP URL 指向自己的宝塔 MCP 服务 - 认证方式为预期的 Bearer Token，且结果中不会完整显示 Token - 不会覆盖项目中已有的其他 MCP 配置 - 只安装需要的 Skills，不执行与接入无关的操作 确认无误后，再按 Claude Code 的提示明确批准配置写入。 ![在 Claude Code 中核对风险并确认写入 MCP 配置](/img/ai-ops/agent/claude-code-mcp/approve-configuration.png) 远程安装文档只是配置来源，不代表已经获得执行任意命令的授权。如果 Claude Code 展示的实际操作超出 MCP 接入和 Skills 安装范围，应拒绝操作并重新核对提示词来源。 ## 5. 确认配置与连接结果 执行完成后，Claude Code 应返回类似结果： - 宝塔 MCP 配置已写入预期范围 - Bearer Token 已配置但未在结果中完整显示 - MCP `initialize` 成功 - `tools/list` 成功，且未出现 TLS、`401` 或 `403` 错误 - 相关 Skills 已被 Claude Code 识别 ![Claude Code 完成宝塔 MCP 配置和连通性验证](/img/ai-ops/agent/claude-code-mcp/configuration-complete.png) 截图中的工具、Skills 数量和配置路径仅为当次环境的结果，实际结果以当前宝塔 MCP、Skill 和 Claude Code 版本为准。 ## 6. 执行首次只读验证 在重新打开的项目中发送一条只读指令，例如： ```text 查看宝塔面板当前状态，只读取 CPU、内存、磁盘、系统负载和服务运行情况，不要修改任何配置。 ``` 如果 Claude Code 能调用宝塔 MCP 并返回服务器资源与服务状态，说明接入成功。 ![通过 Claude Code 查询宝塔服务器服务状态](/img/ai-ops/agent/claude-code-mcp/first-readonly-check.png) 首次验证通过后，再根据实际需要逐步尝试其他操作。涉及删除文件、修改防火墙、重启服务、安装软件等高风险操作时，应仔细核对 Claude Code 的操作计划并保留人工确认。 ## 7. 配置复核与手动兜底 如果上一节的自然语言只读验证已经成功，说明安装提示词完成的自动配置已经生效，**无需再次添加 MCP，也无需修改配置文件**。以下内容只用于命令复核、自动配置未生效或需要调整配置范围的场景。 ### 安装提示词自动配置（推荐） 正常情况下，到这里已经完成接入。需要从命令行复核时，可以运行： ```bash claude mcp list ``` 如果列表中存在 `baota-mcp` 且连接状态正常，不要再次运行 `claude mcp add`，也不要重复修改配置文件。 只有在自然语言验证失败，或命令结果出现以下情况时，才切换到右侧的“命令或配置文件”页签： - `claude mcp list` 看不到 `baota-mcp` - 自动配置写入了当前版本无法识别的位置 - 配置作用范围与预期不一致 - 需要改为使用环境变量保存 Token ### 命令或配置文件（备选） ### 使用 Claude Code 命令添加 截图中的一次安装执行将 MCP 信息写入了项目内的 `.claude/settings.local.json`。如果自然语言验证失败，且 `claude mcp list` 无法识别该配置，请不要继续依赖该路径；当前 Claude Code 官方文档使用 `claude mcp add` 管理 MCP，并按 `local`、`project`、`user` 三种范围保存配置。 需要重新添加时，推荐优先使用命令创建仅对当前项目和当前用户生效的本地范围配置： ```bash claude mcp add --transport http --scope local baota-mcp \ "https://<面板公网IP>:8765/bt-mcp-<实例标识>/mcp" \ --header "Authorization: Bearer <授权令牌>" ``` 命令中的 Token 会进入当前 Shell 的历史记录。需要长期使用时，建议按下面的配置文件方式引用环境变量，并限制配置文件和 Shell 历史的读取权限。 ### 手动修改配置文件 需要在项目中保存可审查、可共享的 MCP 定义时，可在项目根目录创建或修改 `.mcp.json`。该文件对应 `project` 范围，建议只提交不含真实凭据的配置： ```json { "mcpServers": { "baota-mcp": { "type": "http", "url": "https://<面板公网IP>:8765/bt-mcp-<实例标识>/mcp", "headers": { "Authorization": "Bearer ${BAOTA_MCP_TOKEN}" } } } } ``` 启动 Claude Code 前，在当前 Shell 环境中提供 Token： ```bash export BAOTA_MCP_TOKEN='<授权令牌>' claude ``` 如果项目已有 `.mcp.json`，只将 `baota-mcp` 合并到现有 `mcpServers` 中，不要覆盖其他服务。首次加载项目级 MCP 时，Claude Code 会要求确认该项目配置是否可信。 仅希望当前用户在某一个项目中使用时，可以直接修改 `~/.claude.json` 中该项目绝对路径下的 `mcpServers`。下面仅展示需要合并的结构，实际编辑时必须保留文件中的其他字段： ```json { "projects": { "/绝对路径/到/项目": { "mcpServers": { "baota-mcp": { "type": "http", "url": "https://<面板公网IP>:8765/bt-mcp-<实例标识>/mcp", "headers": { "Authorization": "Bearer ${BAOTA_MCP_TOKEN}" } } } } } } ``` 如果希望当前用户的所有项目都能使用，可把相同的 `baota-mcp` 条目合并到 `~/.claude.json` 顶层的 `mcpServers`。由于 `~/.claude.json` 还保存 Claude Code 的其他状态，手动编辑前应先备份，推荐仍使用 `claude mcp add --scope user` 让客户端完成写入。 :::warning 配置范围与凭据 项目级 `.mcp.json` 可能会提交到代码仓库，只能保留 `${BAOTA_MCP_TOKEN}` 占位符。不要写入真实 Token。`local` 和 `user` 范围均保存在用户目录的 `~/.claude.json` 中，但作用范围不同；手动修改时不要把项目路径写错，也不要整文件替换。 ::: 具体配置、项目批准流程和凭据管理方式请参考 [Claude Code 官方 MCP 文档](https://code.claude.com/docs/en/mcp)。 完成兜底配置后，再次执行： ```bash claude mcp list ``` 确认列表中存在宝塔 MCP。随后重启 Claude Code，并重新打开完成配置的同一项目，再回到上一节重新执行自然语言只读验证。 ## 常见问题 ### Auto mode 拒绝安装或写入配置 切换到 Manual mode 或默认交互模式，重新发送安装提示词。在确认窗口中核对目标配置、MCP 地址、认证方式和权限范围后，再明确批准写入。不要通过关闭所有安全检查来绕过拦截。 ### MCP 连接返回 `403 ip denied` 返回【宝塔 MCP 服务】的【接入与体验】页面，将 Claude Code 当前使用的公网出口 IP 加入白名单。不要将白名单长期设置为允许任意来源。 ### MCP 连接返回 `401` 检查 Bearer Token 是否与宝塔 MCP 当前授权信息一致。Token 已更新或疑似泄露时，应在宝塔 MCP 中重新生成授权信息，再更新 Claude Code 配置。 ### `claude mcp list` 看不到宝塔 MCP 优先使用当前官方 `claude mcp add` 命令重新添加服务，或检查项目根目录的 `.mcp.json`。然后从同一项目目录重启 Claude Code。仅在 `.claude/settings.local.json` 中出现 `mcpServers`，不代表当前版本一定会将其识别为 MCP 配置。 ### 出现 TLS 或证书错误 为 MCP 服务配置客户端信任且覆盖访问地址的有效 HTTPS 证书，并确认系统时间和证书链正常。不要使用 `curl -k`、关闭 TLS 校验或导入来源不明证书来绕过错误。 ## 相关文档 - [宝塔 MCP 安装指引](/ai-ops/mcp/installation) - [宝塔 MCP 介绍](/ai-ops/mcp) - [使用 Codex 接入宝塔 MCP](/ai-ops/agent/panel-integration/codex-mcp) - [使用 WorkBuddy 接入宝塔 MCP](/ai-ops/agent/panel-integration/workbuddy-mcp) - [使用 TRAE 接入宝塔 MCP](/ai-ops/agent/panel-integration/trae-mcp) - [使用 DeepSeek Harness 接入宝塔 MCP](/ai-ops/agent/panel-integration/deepseek-harness-mcp) - [通过 Hermes 与 OpenClaw 消息通道接入宝塔 MCP](/ai-ops/agent/panel-integration/hermes-openclaw-mcp) - [宝塔面板 Skill 安装与使用指引](/ai-ops/agent/panel-integration/skill-installation) - [Agent 接入宝塔 MCP 与使用 Skills](/ai-ops/agent/panel-integration) Source: https://docs.bt.cn/ai-ops/agent/panel-integration/claude-code-mcp/index.mdx