TencentOS MCP Server 详细介绍及使用教程
下载
聚焦模式
字号
概述
什么是 MCP
MCP（Model Context Protocol，模型上下文协议）是一种开放标准协议，用于连接 AI 模型与外部工具和数据源。通过 MCP，AI 客户端（如 WorkBuddy、 Cursor、Claude Desktop、CodeBuddy 等）能够以标准化的方式调用外部工具，实现对真实系统的操作和数据获取。快速使用请参见 快速开始。
TencentOS MCP Server 是什么
TencentOS MCP Server 是专为 TencentOS/OpenCloudOS 设计的 Linux 运维 MCP 工具。它通过 MCP 协议为 AI 客户端提供了一套完整的 Linux 运维工具集（22 个工具，覆盖 10 大运维场景），使 AI 能够通过自然语言直接执行系统运维操作。
您只需在 AI 客户端中输入自然语言指令，如"看一下这台机器的 CPU 使用情况"，TencentOS MCP Server 即可自动调用对应的运维工具，返回结构化的诊断结果。
TencentOS MCP Server 可以解决什么问题
传统 Linux 运维依赖手工输入命令、记忆复杂参数，排障效率低且对人员技能要求高。TencentOS MCP Server 解决了以下痛点：
传统方式 | MCP 智能运维 |
需要记忆大量命令和参数 | 自然语言提问，AI 自动调用工具 |
手动逐台登录服务器 | 一个 MCP Server 管理多台主机 |
命令输出难以快速解读 | 结构化 JSON 输出，AI 自动分析 |
需要安装各种监控 Agent | 通过 SSH 远程执行，零侵入 |
排障流程依赖个人经验 | AI 内置运维实践指引 |
架构说明
整体架构
设计理念
AI 原生：所有工具返回结构化 JSON，AI 可直接解析和推理
零侵入：目标主机只需开放 SSH，无需安装任何 Agent
安全第一：所有操作只读，多层安全防护，防止命令注入
开箱即用：22 个工具覆盖常见运维场景，安装即可使用
功能特性
22 个 tools 工具一览
TencentOS MCP Server 提供 22 个开箱即用的运维工具，覆盖系统信息、服务管理、进程分析、日志查看、网络诊断、性能分析、软件包查询、安全审计、内核参数、eBPF 追踪等 10 个领域，用于解决 Linux 运维常见问题。
说明：所有工具均为只读操作，不会对系统进行任何修改。主机的添加和删除仅通过 CLI 命令操作，MCP 接口只提供只读查询。
系统运维工具（19 个）
分类 | 工具名称 | 能力说明 |
系统信息 | get_system_info | 用于查询 OS 版本、内核版本、主机名、架构和运行时间等信息 |
| get_hardware_info | 用于查询 CPU、内存、磁盘等信息 |
服务管理 | get_service_info | 用于查询运行服务等信息 |
进程分析 | list_processes | 用于查询按 CPU 使用率排序的 Top N 进程列表等信息 |
日志查看 | get_journal_logs | 用于查询 systemd journal 日志信息（支持按时间/优先级/服务/关键词过滤） |
| get_system_messages | 用于查询系统消息日志信息（支持关键词过滤） |
网络诊断 | get_listening_ports | 用于查询系统监听端口信息 |
防火墙 | get_iptables_rules | 用于查询 iptables 防火墙规则信息（filter/nat/mangle/raw 四表，含规则编号与流量统计） |
性能分析 | get_perf_overview | 用于查询 CPU/内存/IO/网络四大维度综合性能信息 |
软件包 | get_package_info | 用于查询指定软件包的版本、架构、描述等信息 |
安全审计 | get_selinux_status | 用于查询 SELinux 状态及最近的 AVC 拒绝记录信息 |
| get_login_history | 用于查询登录成功/失败历史及安全告警信息 |
| get_updateinfo_security | 用于查询可用安全更新公告信息（yum/dnf 系发行版） |
内核管理 | get_sysctl_params | 用于查询内核参数信息（支持前缀过滤，如 `net.ipv4`） |
| list_kernel_modules | 用于查询已加载内核模块信息（支持名称过滤） |
eBPF 追踪 | get_ebpf_status | 用于查询 eBPF 追踪工具（nettrace/perf-prof）安装状态信息 |
| ebpf_trace | 用于追踪系统事件信息（tcp/bio/exec，基于内核原生接口，无需安装额外工具） |
网络追踪 | nettrace | 用于追踪网络数据包路径信息（基于 eBPF，需安装 nettrace） |
性能分析 | perf_prof | 用于分析系统性能瓶颈信息（基于 eBPF，需安装 perf-prof） |
主机管理工具（3 个）
分类 | 工具名称 | 能力说明 |
主机管理 | list_managed_hosts | 用于查询所有已纳管主机列表信息 |
| get_managed_host | 用于查询单个主机的详细信息 |
| test_managed_host | 用于测试主机 SSH 连通性信息（支持单台或批量测试） |
TencentOS 深度集成能力
nettrace 网络追踪
nettrace 是 TencentOS 独有的基于 eBPF 的内核级网络包追踪工具，支持四种追踪模式：
模式 | 说明 | 适用场景 |
basic | 精简模式（默认），每包 1~2 行 | 快速定位网络问题 |
life | 完整生命周期追踪，每包 14~22 行 | 深入分析数据包流转路径 |
drop | 丢包追踪（需 v1.2.9+） | 定位网络丢包位置和原因 |
diag | 诊断模式（需 v1.2.9+） | 综合网络故障诊断 |
特性：
通过
max_packets 参数控制抓包数量（默认 50，上限 100），输出量可控支持按协议（tcp/udp/icmp）、源/目标 IP、源/目标端口过滤
超时自动退出，防止长时间占用资源
perf-prof 性能分析
perf-prof 是基于 perf_event 和 eBPF 的内核性能分析工具，支持多维度性能分析：
分析类型 | 说明 | 典型用途 |
cpu | CPU 使用率分析（默认） | 定位 CPU 热点函数 |
syscall | 系统调用追踪 | 分析系统调用延迟 |
io | 磁盘 IO 延迟分析 | 定位 IO 瓶颈 |
mem | 内存分配分析 | 排查内存泄漏 |
sched | 调度延迟分析 | 分析进程调度问题 |
双模传输
MCP Server 支持两种传输模式，适应不同使用场景：
对比项 | stdio 模式 | Streamable HTTP 模式 |
适用场景 | 本地开发，客户端与服务在同一台机器 | 远程部署，多客户端共享 |
启动方式 | 客户端自动拉起进程，无需手动启动 | 需先在服务器上手动启动 HTTP 服务 |
Token 认证 | 不需要 | 必须配置 |
网络要求 | 无需网络 | 需要监听端口（默认 8001） |
SSH 远程管理 | 支持（通过本地 SSH 连接远程主机） | 支持 |
多客户端 | 不支持（一对一） | 支持（一对多） |
SSH 多主机管理
通过一个 MCP Server 可管理多台 Linux 服务器
通过 SSH 密钥认证远程执行命令，无需在目标主机安装任何 Agent
内置连接池管理和自动重连机制
快速开始
本节提供从零开始使用 MCP 的步骤指南。
第 1 步：安装 TencentOS MCP Server
TencentOS AI 增强版镜像已经预装了该组件，无需重复安装。在 云服务器实例购买页，公共镜像选择 TencentOS > TencentOS Server 4 AI 增强版镜像，其他配置参数请参见 通过购买页创建实例。
说明：该组件支持离线安装，若您有在其他环境使用的需要，可联系腾讯云人员，获取 rpm 包。
第 2 步：初始配置
1. 使用 root 账户登录实例后，执行命令生成 AI 客户端校验的 token（token 需要保密，以防被泄露）。
tencentos-mcp-server token generate
2. 启动 MCP Server 服务。
systemctl start tencentos-mcp-server
3. 验证安装，在本地执行。
# 验证服务健康状态（HTTP 模式）curl http://127.0.0.1:8001/health
返回示例如下，则表明正常启动。
{"status": "healthy","version": "1.0.0","transport": "streamable-http","auth": "enabled","tools_count": 22}
第 2 步：配置 AI（智能体）客户端
在智能体客户端（WorkBuddy、Claude Code 等）配置文件中添加以下配置：
说明：
{"mcpServers": {"tencentos": {"url": "http://<your server-ip>:8001/mcp","headers": {"Authorization": "Bearer <your-token>"}}}}
第 3 步：添加纳管主机（可选）
说明：若您需要通过 MCP Server 所在主机，管理其他未安装 MCP Server 的主机，则需要执行该步骤统一纳管。
1. 登录实例，在 MCP Server 所在的主机，以 root 执行指令生成密钥。
# 生成密钥（如果还没有，推荐使用 ed25519）ssh-keygen -t ed25519
2. 传递密钥，将密钥传递至需要纳管的主机。
# 分发公钥到目标主机（以198.51.100.10举例）ssh-copy-id root@198.51.100.10
3. 添加主机，分别执行添加主机、添加后查看主机等指令。
# 添加主机（自动测试 SSH 连通性，以198.51.100.10举例）tencentos-mcp-server host add 198.51.100.10# 查看已添加的主机tencentos-mcp-server host list
第 4 步：开始使用
在 AI 客户端中用自然语言提问即可：
"看一下这台机器的 CPU 和内存使用情况""有哪些服务是异常的？""帮我查一下最近有没有 OOM 事件""检查一下 SELinux 状态和最近的登录记录""用 nettrace 追踪一下 TCP 丢包""分析一下 198.51.100.10 上的磁盘 IO 性能"
使用示例
场景一：系统健康检查
帮我全面检查一下这台机器的健康状态
AI 调用：
1.
get_system_info ：获取系统基本信息2.
get_hardware_info ：获取 CPU/内存/磁盘状态3.
get_perf_overview ：获取性能概览4.
get_service_info ：检查异常服务场景二：网络故障排查
我的 Web 服务器 198.51.100.10 连接很慢，帮我排查一下
AI 调用：
1.
list_managed_hosts ：确认主机已纳管2.
get_listening_ports(host="198.51.100.10") ：检查端口监听状态3.
get_perf_overview(host="198.51.100.10") ：检查资源使用4.
nettrace(dport=80, host="198.51.100.10") ：追踪网络包场景三：安全审计
检查一下最近有没有可疑的登录行为
AI 调用：
1.
get_login_history(count=50, include_failed=True) ：获取登录历史2.
get_selinux_status ：检查 SELinux 状态3.
get_updateinfo_security ：查看安全公告场景四：性能分析
帮我分析一下哪个进程占用了最多的 CPU
AI 调用：
1.
list_processes ：获取 Top N 进程2.
get_perf_overview ：获取性能概览3.
perf_prof(profile_type="cpu", duration=5) ：进行 CPU 热点分析场景五：日志分析
查一下最近一小时的错误日志
AI 调用：
1.
get_journal_logs(priority="err", since="1 hour ago") ：获取错误级别日志2.
get_system_messages(grep="error") ：搜索系统消息中的错误场景六：多主机管理
帮我看看所有纳管主机的连通性
AI 调用：
1.
list_managed_hosts ：获取主机列表2.
test_managed_host ：批量测试连通性CLI 命令参考
服务管理
# HTTP 模式启动 指定端口tencentos-mcp-server serve --transport streamable-http --host 0.0.0.0 --port 8001# systemd 管理（部署包安装时使用 --enable-service）systemctl start tencentos-mcp-serversystemctl stop tencentos-mcp-serversystemctl restart tencentos-mcp-serversystemctl status tencentos-mcp-server# 查看安装信息tencentos-mcp-server info
Token 管理
# 生成 API Tokentencentos-mcp-server token generate# 强制重新生成（覆盖已有 Token）tencentos-mcp-server token generate --force# 撤销 Tokentencentos-mcp-server token revoke
说明：Token 重新生成后，需重启 MCP Server 服务生效。
主机管理
# 添加主机（自动测试 SSH 连通性）tencentos-mcp-server host add 198.51.100.10# 列出所有纳管主机tencentos-mcp-server host list# JSON 格式输出tencentos-mcp-server host list --format json# 测试单台主机连通性tencentos-mcp-server host test 198.51.100.10# 批量测试所有主机tencentos-mcp-server host test-all# 删除主机tencentos-mcp-server host remove 198.51.100.10
健康检查
HTTP 模式下提供
/health 端点（无需 Token）：curl http://127.0.0.1:8001/health
安全设计
TencentOS MCP Server 采用多层安全防护设计，适合生产环境部署：
安全层面 | 措施 | 说明 |
操作安全 | 默认只读 | 所有 22 个工具均为只读操作，无任何写入或修改 |
输入安全 | 输入消毒 | 过滤 30+ 种危险字符（引号、制表符、glob、重定向、Unicode 控制字符等） |
| 参数转义 | 使用 shlex.quote 对所有参数值进行 POSIX shell 安全转义 |
| 白名单校验 | 枚举参数使用白名单校验；IP/端口/CPU 范围使用正则校验 |
| 路径遍历防护 | 禁止 .. 和特殊字符，防止目录穿越攻击 |
执行安全 | 命令长度限制 | 本地执行命令长度上限 4096 字符 |
| 环境变量清理 | 清理 LD_PRELOAD、IFS、BASH_ENV 等危险环境变量 |
| 超时进程清理 | 命令在独立进程组中执行，超时后回收整组进程 |
| Token 认证 | HTTP 模式 Bearer Token 鉴权，Token AES 加密存储 |
| TLS/HTTPS | 支持 SSL 证书配置，生产环境加密传输 |
传输安全 | 速率限制 | Token 级别 + 全局级别双重频率控制 |
连接安全 | SSH Host Key 验证 | 默认 TOFU 策略，首次信任并记录，后续验证防中间人攻击 |
| SSH 密钥认证 | 统一使用证书方案，不支持密码登录 |
数据安全 | 审计日志 | 所有工具调用记录到 JSONL 文件（含实际执行命令） |
| 配置文件保护 | Token 加密存储，密钥文件和配置文件权限自动设置为 600 |
MCP 客户端配置
常用客户端配置文件位置
客户端 | 配置文件路径 |
Cursor | .cursor/mcp.json（项目目录下） |
Claude Desktop (macOS) | ~/Library/Application Support/Claude/claude_desktop_config.json |
Claude Desktop (Windows) | %APPDATA%\\Claude\\claude_desktop_config.json |
CodeBuddy | ~/.codebuddy/mcp.json |
Streamable HTTP 模式配置
{"mcpServers": {"tencentos": {"url": "http://<server-ip>:8001/mcp","headers": {"Authorization": "Bearer <your-token>"}}}}
说明：将
<server-ip> 替换为服务器实际 IP，<your-token> 替换为 tencentos-mcp-server token generate 生成的 Token。常见问题
连接相关
SSH 连接远程主机失败？
您可参见以下步骤排查：
1. 确认 SSH 密钥已分发：
ssh-copy-id root@<IP>2. 确认手动 SSH 可连接：
ssh root@<IP>3. 检查密钥权限：
ls -la ~/.ssh/id_*（权限需 ≤ 600）4. 查看详细错误：
tencentos-mcp-server host test <IP>
如何管理远程主机上 SSH 端口不是 22 的情况？
添加主机时可指定端口：
tencentos-mcp-server host add 198.51.100.10 -p 36000
使用相关
AI 调用 nettrace 工具时提示未安装？
nettrace 是 TencentOS 独有工具，需要手动安装：
# 在目标主机上执行yum install nettrace
如果目标系统不支持 nettrace，可使用
ebpf_trace 作为轻量级替代。
Token 重新生成后服务未更新？
重新生成 Token 后需重启服务：
systemctl restart tencentos-mcp-server
说明：MCP 功能当前为技术预览（Technology Preview）版本，尚未经过大规模的生产环境验证。AI 生成的诊断结论和操作建议仅供参考，用户应在执行任何操作前自行验证其正确性和适用性，并对操作结果承担全部责任。腾讯云不对因使用 AI 运维技能产生的任何直接或间接损失承担责任。
文档反馈