---
title: "宝塔MCP安装指引"
description: "介绍宝塔 MCP 服务的安装与接入方法，包括面板及 Python 版本准备、插件安装、8765 端口放行、IP 白名单、Agent 自动或手动配置，以及常见问题排查。"
---

> 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.

# 宝塔MCP安装指引

宝塔 MCP 服务可将宝塔面板的运维能力接入支持 MCP 的 Agent。安装完成后，Agent 可以通过授权的 MCP 服务查询和管理服务器。

> 首次使用前，可先阅读[宝塔 MCP 介绍](/ai-ops/mcp)，了解它与宝塔 AI 助手的区别及工作方式。

:::warning 安装建议
建议先在非生产环境完成安装和功能验证。生产环境操作前，请备份重要数据，并仅向可信 IP 开放 MCP 服务端口。
:::

## 安装前准备

开始安装前，请确认：

- 已取得宝塔面板管理员权限和服务器终端权限
- 面板版本为正式版 13.0
- 面板运行环境已升级到 Python 3.13
- Agent 支持连接远程 MCP 服务
- Agent 所在网络可以访问服务器的 `8765` 端口

## 1. 更新面板和 Python

如果当前面板版本已经满足要求，可直接更新 Python；否则请先安装或升级到宝塔面板 13.0。

### 已有面板升级到 13.0

已有正式版面板的用户可在面板首页右上角点击【更新】按钮，升级到 13.0。

### 全新安装 13.0

在服务器终端中执行：

```bash
curl -sSO http://download.bt.cn/install/install13.sh && bash install13.sh
```

### 更新 Python 到 3.13

在非面板终端中执行：

```bash
bash /www/server/panel/script/upgrade_py313_bundle.sh
```

也可以登录面板，点击右上角的【更新】按钮完成升级。

![通过面板更新版本](/img/user-guide/ai/mcp-installation/panel-upgrade.png)

升级完成后，可在面板首页确认当前版本。

![在面板首页确认版本](/img/user-guide/ai/mcp-installation/panel-version.png)

## 2. 安装宝塔 MCP 服务

1. 登录宝塔面板
2. 进入【软件商店】
3. 搜索“宝塔 MCP”
4. 找到【宝塔 MCP 服务】并点击【安装】

![在软件商店安装宝塔 MCP 服务](/img/user-guide/ai/mcp-installation/plugin-search.png)

## 3. 放行 8765 端口

安装完成后，需要同时在宝塔面板防火墙和云服务器厂商的安全组或防火墙中放行 `8765` 端口。

### 宝塔面板防火墙

进入【安全】页面，添加一条入站规则：

- 协议：TCP
- 端口：`8765`
- 来源：优先填写 Agent 的固定公网出口 IP

![在宝塔面板防火墙放行 8765 端口](/img/user-guide/ai/mcp-installation/panel-firewall.png)

### 云服务器防火墙

如果服务器部署在云平台，还需要在云平台控制台的安全组或防火墙中放行 `8765` 端口。

![在云服务器防火墙放行 8765 端口](/img/user-guide/ai/mcp-installation/cloud-firewall.png)

:::tip
不建议将 `8765` 端口向所有来源开放。无法确认 Agent 出口 IP 时，可先临时放行完成连通性测试，测试结束后立即收紧规则。
:::

## 4. 设置 IP 白名单

1. 在软件商店中打开【宝塔 MCP 服务】
2. 进入【接入与体验】
3. 按页面提示添加 Agent 的公网出口 IP

![宝塔 MCP 服务接入设置](/img/user-guide/ai/mcp-installation/ip-whitelist.png)

![添加 Agent 的公网出口 IP](/img/user-guide/ai/mcp-installation/ip-whitelist-add.png)

:::warning
IP 段放通暂不可用，请填写单个公网 IP。配置错误会导致 Agent 无法连接 MCP 服务。
:::

## 5. 配置 Agent

支持自动配置和手动配置两种方式，推荐优先使用自动配置。

### 方式一：使用提示词自动配置

1. 在插件的【接入与体验】页面生成并复制安装提示词
2. 将提示词发送给需要接入的 Agent
3. 按 Agent 的提示完成 MCP 服务安装与连接

![复制 MCP 安装提示词](/img/user-guide/ai/mcp-installation/install-prompt.png)

![Agent 自动完成 MCP 配置](/img/user-guide/ai/mcp-installation/agent-auto-config.png)

### 方式二：手动配置

1. 打开插件的【安全授权】页面
2. 获取 MCP 服务器地址和授权令牌
3. 将信息填入 Agent 的 MCP 配置文件

![获取 MCP 服务器地址和授权信息](/img/user-guide/ai/mcp-installation/security-authorization.png)

参考配置：

```json
{
  "mcpServers": {
    "baota-mcp": {
      "url": "https://<面板公网IP>:8765/bt-mcp-<实例标识>/mcp",
      "headers": {
        "Authorization": "Bearer <授权令牌>"
      },
      "disabled": false
    }
  }
}
```

:::danger 保护授权信息
MCP 服务器地址和授权令牌属于敏感信息。请勿提交到公开代码仓库、粘贴到公开聊天或分享给无关人员。如怀疑令牌泄露，请立即在插件中重新生成授权信息。
:::

### 不同 Agent 接入指南

各 Agent 的配置位置、权限模式和生效方式不同。完成 MCP 服务安装、端口放行、HTTPS 和 IP 白名单设置后，可继续阅读对应客户端教程：

- [使用 Codex 接入宝塔 MCP](/ai-ops/agent/panel-integration/codex-mcp)
- [使用 WorkBuddy 接入宝塔 MCP](/ai-ops/agent/panel-integration/workbuddy-mcp)
- [使用 Claude Code 接入宝塔 MCP](/ai-ops/agent/panel-integration/claude-code-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)

未列出的 Agent 可以先参考本页的通用 JSON，再根据客户端文档调整配置文件路径、远程 HTTP 传输字段和认证请求头。不要直接照抄其他 Agent 的配置文件路径。

## 6. 验证连接

完成配置后，让 Agent 执行一项只读操作，例如查询服务器基本信息。如果 Agent 能正常返回服务器信息，即表示 MCP 服务已成功接入。

![通过 Agent 调用宝塔 MCP 服务](/img/user-guide/ai/mcp-installation/agent-call-success.png)

## 申请可信 IP 证书

部分系统需要有效的 HTTPS 证书链才能连接 MCP 服务。可在宝塔面板中申请可信 IP 证书：

1. 进入【设置】→【安全设置】→【面板 SSL】
2. 打开面板 SSL
3. 选择 IP 证书申请入口并完成申请
4. 安装证书后，重新获取 MCP 接入信息

![进入面板 SSL 设置](/img/user-guide/ai/mcp-installation/panel-ssl-settings.png)

![申请可信 IP 证书](/img/user-guide/ai/mcp-installation/apply-ip-certificate.png)

## 常见问题

### 安装提示词获取失败，提示“未探测到有效证书链”或“HTTPS 未就绪”

按照[申请可信 IP 证书](#申请可信-ip-证书)中的步骤申请并安装面板 SSL 证书，然后重新获取安装提示词。

### 获取接入信息时提示 HTTP 500

确认面板运行环境已经升级到 Python 3.13。升级完成后，卸载并重新安装【宝塔 MCP 服务】插件。

### Agent 无法连接 MCP 服务

依次检查：

1. 宝塔面板防火墙是否已放行 TCP `8765` 端口
2. 云服务器安全组或防火墙是否已放行 TCP `8765` 端口
3. Agent 的公网出口 IP 是否已加入插件白名单
4. MCP 服务器地址和授权令牌是否填写正确
5. 面板 SSL 证书是否有效

Source: https://docs.bt.cn/ai-ops/mcp/installation/index.mdx