Tencentos

FreeNot checked

MCP Server for TencentOS Server — system telemetry, diagnostics, and recommendations

by guoningzhang20

GitHub Embed

About

MCP Server for TencentOS Server — system telemetry, diagnostics, and recommendations

README

MCP Server for TencentOS Server — 系统遥测、故障诊断、补丁评估、合规审计、配置调优

基于 Model Context Protocol (MCP) 构建，让 AI 助手（如 CodeBuddy / Cursor / VS Code Copilot）能够直接读取和分析 TencentOS Server 系统状态。

✨ 核心特性

基础层 — 系统遥测（对标 Red Hat linux-mcp-server）

模块	工具	说明
system_info	`get_system_info` / `get_cpu_info` / `get_memory_info` / `get_disk_usage`	OS、内核、CPU、内存、磁盘
processes	`list_processes`	进程列表（按 CPU/内存排序）
services	`list_services` / `get_service_status`	systemd 服务状态
network	`get_network_info` / `get_network_connections`	网络接口、连接
storage	`get_block_devices`	块设备
logs	`query_logs`	journalctl 日志查询

增强层 — 诊断与建议（TencentOS 独有）

模块	工具	解决的问题
① 补丁影响评估	`assess_patch_impact` / `list_security_advisories` / `check_patch_dependencies`	打补丁前评估对业务的影响，推荐修复策略
② 故障诊断	`diagnose_system` / `get_error_timeline` / `check_resource_pressure`	多源日志关联分析，读懂机器状态
③ 合规举证	`audit_operations` / `check_compliance` / `get_privileged_operations`	谁在什么时候操作了什么，审计取证
④ 补丁版本管理	`get_patch_history` / `compare_patch_status` / `get_kernel_history`	补丁履历 + 版本 Gap 分析 + CVE 交叉比对
⑤ 系统配置调优	`analyze_system_tuning` / `get_workload_profile` / `check_kernel_parameters`	负载画像 + 参数最佳实践对比 + 调优建议

🔒 所有操作均为只读。增强层仅提供诊断分析和建议，不会修改任何系统配置。

🎯 三种部署模式

先看清楚你要的是哪种模式，再看对应章节的安装步骤。

模式	MCP Server 装在哪	被管机装什么	适用场景
A. 本地模式	你的机器 / 被管机本身	—	管一台本机，最简单
B. 跨机 SSH 模式	一台"管控机"	零部署（只需一个 SSH 账号）	管远程一台或多台服务器
C. 多客户端共享 HTTP	一台"管控机" + 开启 HTTP 端口	同 B	团队多人共用同一套 MCP

💡 推荐路径：先用 A 跑通 → 再切 B 验证跨机 → 有团队场景再上 C

💻 本地 stdio 模式（模式 A）

最简单的起步方式：MCP Server 和 IDE 客户端跑在同一台机器上，管的也是这台机器。适合开发机体检、功能试跑。

1. 环境要求

TencentOS Server 4 / CentOS 8+ / RHEL 8+（被管目标）
Python 3.9+
管控机执行 dnf / systemctl / journalctl 需要合适的权限（通常是 root 或 sudoers）

2. 克隆 + 安装

git clone https://github.com/guoningzhang20/tencentos-mcp-server.git
cd tencentos-mcp-server
pip install .

安装完成后，系统里会多一个可执行命令：/usr/local/bin/tencentos-mcp-server（或你 venv 的 bin 目录）。

3. 选一种传输协议启动

# ① stdio 模式（默认）— 由 MCP 客户端（IDE）自动拉起，不要手动执行
#    配置方法见下方「IDE 配置」章节
tencentos-mcp-server

# ② SSE 模式 — 启动 HTTP 服务，适合远程连接或多客户端共享
tencentos-mcp-server --transport sse --host 0.0.0.0 --port 8000

# ③ Streamable HTTP 模式 — MCP 最新推荐协议
tencentos-mcp-server --transport streamable-http --host 0.0.0.0 --port 8000

⚠️ stdio 模式通过 stdin/stdout 通信，直接在终端执行会看到进程"卡住"等输入——这是正常行为，按 Ctrl+C 退出。如需手动测试功能，请用 SSE 或 Streamable HTTP 模式。

三种传输协议对比：

协议	启动方式	适用场景
`stdio`	MCP 客户端（IDE）自动拉起子进程	本地 IDE 插件（CodeBuddy / Cursor），无需手动运行
`sse`	手动启动 HTTP 服务，客户端连 `http://host:port/sse`	远程服务器、多客户端共享
`streamable-http`	手动启动 HTTP 服务，客户端连 `http://host:port/mcp`	MCP 协议最新标准，推荐新项目使用

4. IDE 配置（CodeBuddy / Cursor / VS Code）

编辑 ~/.workbuddy/mcp.json（或对应 IDE 的 MCP 配置文件）：

{
  "mcpServers": {
    "tencentos": {
      "type": "stdio",
      "command": "tencentos-mcp-server"
    }
  }
}

保存 → 重启 IDE → 工具列表里能看到 tencentos 分组下的 26 个工具即为成功。

🌐 跨机 SSH 模式（模式 B）

这是本项目最推荐的模式：一台"管控机"跑 MCP Server，通过 SSH 远程操作多台被管目标机，被管机零部署。

架构

┌────────────┐          ┌──────────────────┐    SSH (asyncssh)   ┌─────────────────┐
│ AI 客户端  │  stdio   │  管控机           │ ──────────────────► │ 被管目标机       │
│ (IDE 插件) │ ───────► │  MCP Server       │                     │ 零部署           │
│            │ ◄─────── │  + SSH 密钥       │ ◄────────────────── │ TencentOS 4      │
└────────────┘          └──────────────────┘                     └─────────────────┘

Step 1 — 在管控机装 MCP Server

git clone https://github.com/guoningzhang20/tencentos-mcp-server.git
cd tencentos-mcp-server
pip install .

Step 2 — 打通 SSH 免密到被管机

# 管控机上生成密钥（如已有可跳过）
ssh-keygen -t ed25519 -f ~/.ssh/id_ed25519 -N ''

# 把公钥下发到被管机
ssh-copy-id -i ~/.ssh/id_ed25519.pub root@<TARGET_HOST>

# 权限必须严格
chmod 700 ~/.ssh
chmod 600 ~/.ssh/id_ed25519

# 首次手动 SSH 一次，把被管机指纹写入 known_hosts
ssh root@<TARGET_HOST> 'hostname && uname -r'

⚠️ 踩坑点：known_hosts 里必须有被管机条目，否则 asyncssh 会报 Host key verification failed。如果你想禁用主机密钥校验（仅限测试环境），设置 TENCENTOS_MCP_SSH_KNOWN_HOSTS=none。

Step 3 — 启动服务并指定被管机

TENCENTOS_MCP_HOST=<TARGET_HOST> \
TENCENTOS_MCP_USER=root \
TENCENTOS_MCP_SSH_KEY_PATH=/root/.ssh/id_ed25519 \
tencentos-mcp-server --transport streamable-http --host 0.0.0.0 --port 8000

Step 4 — 验证 MCP 真的在管被管机（三方对照法）

这是今天调试最值钱的经验：光看 MCP 返回不够，必须和 SSH 直连结果对照。

# A. 直连被管机看真实 hostname
ssh root@<TARGET_HOST> 'hostname && uname -r && uptime -s'

# B. 通过 MCP 调 get_system_info，对比 hostname / kernel / 启动时间
curl -X POST http://127.0.0.1:8000/mcp \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_system_info","arguments":{}}}'

# A 和 B 的 hostname 一致 → 跨机管理链路打通

⚠️ 常见误判：不要凭"主机名像"就下结论，同网段多台机器 hostname 规则可能雷同。一律三方对照（MCP 返回 vs SSH 直连 vs 云控制台）。

🏢 多客户端共享 HTTP 模式（模式 C）

在模式 B 基础上，加 API Key 认证+ 防火墙+ systemd 托管，让团队多人共用同一台 MCP Server。

Step 1 — 生成 API Key

openssl rand -hex 32
# 输出示例：7f3a8e2d9c1b4f5e6...（64 位随机 hex，请保管好）

这个 key 是客户端的"暗号"，服务端启动参数和客户端配置必须完全一致。

Step 2 — 启动服务（带认证）

tencentos-mcp-server \
  --transport streamable-http \
  --host 0.0.0.0 \
  --port 8000 \
  --api-key <YOUR_API_KEY>

参数	作用
`--transport streamable-http`	MCP 最新推荐协议，标准 HTTP
`--host 0.0.0.0`	监听所有网卡；`127.0.0.1` 则仅本机
`--port 8000`	任选未被占用的端口
`--api-key`	Bearer Token 认证密钥，配合 `0.0.0.0` 必开

Step 3 — 开放防火墙 + 腾讯云安全组

# firewalld
firewall-cmd --permanent --add-port=8000/tcp
firewall-cmd --reload

如果机器在腾讯云，还必须去云控制台「安全组」里放行 8000/tcp 入方向——这是最容易漏的一步，防火墙通了但安全组没开，外面死活连不上。

Step 4 — 验证服务可用

# 1. 没 Key 应返回 401
curl -i http://127.0.0.1:8000/mcp

# 2. 带 Key 的完整 JSON-RPC 请求应返回 MCP 响应
curl -i -X POST http://127.0.0.1:8000/mcp \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'

⚠️ Accept 头必须同时带 application/json, text/event-stream，少任何一个 MCP 服务端都会返回 406 Not Acceptable——这个错误排查起来巨耗时，今天就踩过。

Step 5 — 客户端配置

{
  "mcpServers": {
    "tencentos": {
      "type": "http",
      "url": "http://<你的管控机 IP>:8000/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_API_KEY>"
      }
    }
  }
}

三个字段核对清单：

type：必须显式写 "http"，否则部分客户端会按 stdio 去拉子进程，报 spawn ENOENT
url：/mcp 路径不能改
Authorization：Bearer + 空格 + API Key（大小写敏感，别漏空格）

Step 6 — 生产化（systemd 托管，必做）

前台运行 SSH 一断服务就死，生产环境必须用 systemd：

# /etc/systemd/system/tencentos-mcp.service
[Unit]
Description=TencentOS MCP Server
After=network.target

[Service]
Type=simple
User=root
Environment="TENCENTOS_MCP_API_KEY=<YOUR_API_KEY>"
Environment="TENCENTOS_MCP_HOST=<TARGET_HOST>"
Environment="TENCENTOS_MCP_USER=root"
Environment="TENCENTOS_MCP_SSH_KEY_PATH=/root/.ssh/id_ed25519"
ExecStart=/usr/local/bin/tencentos-mcp-server \
  --transport streamable-http \
  --host 0.0.0.0 \
  --port 8000
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now tencentos-mcp
sudo systemctl status tencentos-mcp

# 查日志
journalctl -u tencentos-mcp -f

💡 注意：跨机 SSH 模式的所有环境变量（TENCENTOS_MCP_HOST 等）都要用 Environment= 在 unit 文件里声明，当前 shell 的环境变量 systemd 拿不到。

Step 7 — 公网暴露（HTTPS + 反向代理）

如果 MCP Server 要暴露到公网，Bearer Token 明文 HTTP 传输等于裸奔，必须加 HTTPS。推荐 Nginx 反代：

# /etc/nginx/conf.d/mcp.conf
server {
    listen 443 ssl http2;
    server_name mcp.yourdomain.com;

    ssl_certificate     /etc/letsencrypt/live/mcp.yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/mcp.yourdomain.com/privkey.pem;

    location /mcp {
        proxy_pass http://127.0.0.1:8000/mcp;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;

        # Streamable HTTP 长连接必需
        proxy_buffering off;
        proxy_read_timeout 3600s;
        proxy_send_timeout 3600s;
        proxy_set_header Connection "";
    }
}

此时服务端启动参数改为 --host 127.0.0.1（让 Nginx 作为唯一入口），客户端 url 改为 https://mcp.yourdomain.com/mcp。

🐳 容器运行（可选）

# 构建
docker build -f Containerfile -t tencentos-mcp-server:latest .

# 运行（本地模式）
docker run -i --rm tencentos-mcp-server:latest

# 运行（SSH 远程模式）
docker run -i --rm \
  -v ~/.ssh:/root/.ssh:ro \
  -e TENCENTOS_MCP_HOST=<TARGET_HOST> \
  -e TENCENTOS_MCP_USER=root \
  -e TENCENTOS_MCP_SSH_KEY_PATH=/root/.ssh/id_ed25519 \
  tencentos-mcp-server:latest

完整配置参见 mcp-config-example.json。

🆘 常见问题排查

现象	原因	解决
客户端报 `spawn tencentos ENOENT`	配置里缺 `"type": "http"`，被当 stdio 拉子进程	加 `"type": "http"`
返回 `401 Unauthorized`	API Key 不匹配，或缺 `Bearer` 前缀	检查 Header 与服务端 `--api-key` 一致
返回 `406 Not Acceptable`	缺 `Accept: application/json, text/event-stream`	补全 Accept 头
返回 `connection refused` / 超时	网络不通	`curl <url>` 在客户端机器上测；检查 firewalld 和云安全组
SSH 断开后服务就停	前台进程随终端退出	上 systemd 托管（Step 6）
MCP 返回的 hostname / kernel 和预期不符	跨机配置不对 / 主机名雷同误判	三方对照：MCP 返回 vs `ssh root@<ip>` 直连 vs 云控制台
`Host key verification failed`	管控机 known_hosts 没有被管机指纹	先手动 `ssh root@<ip>` 一次接受指纹
systemd 启动成功但环境变量没生效	用了当前 shell 的变量	所有变量必须写到 unit 文件的 `Environment=` 里
MCP 进程存在但工具调用报错	SSH 私钥权限不对	`chmod 700 ~/.ssh && chmod 600 ~/.ssh/id_ed25519`

🏗️ 架构

┌──────────────────────────────────────────────────────────┐
│                    AI Agent (IDE)                         │
│               CodeBuddy / Cursor / VS Code               │
└───────┬──────────────┬───────────────┬───────────────────┘
        │ stdio        │ SSE          │ Streamable HTTP
        │ (子进程)      │ (HTTP 长连接) │ (HTTP 双向流)
        │              │ /sse         │ /mcp
┌───────▼──────────────▼───────────────▼───────────────────┐
│              TencentOS MCP Server                        │
│                                                          │
│  ┌─────────────────────────────────────────────────────┐ │
│  │  传输层 (Transport)                                  │ │
│  │  stdio  │  SSE (uvicorn)  │  Streamable HTTP        │ │
│  ├─────────────────────────────────────────────────────┤ │
│  │  基础层 (Base)                                       │ │
│  │  system_info │ processes │ services                  │ │
│  │  network     │ storage   │ logs                      │ │
│  ├─────────────────────────────────────────────────────┤ │
│  │  增强层 (Enhanced) — TencentOS 独有                  │ │
│  │  patch_impact │ diagnostics │ compliance             │ │
│  │  patch_history│ system_tuning                        │ │
│  ├─────────────────────────────────────────────────────┤ │
│  │  执行层 (Executor)                                   │ │
│  │  本地 subprocess  ←→  SSH asyncssh                   │ │
│  └─────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────┘
                     │
          ┌──────────┴──────────┐
          ▼                     ▼
   ┌─────────────┐    ┌─────────────────┐
   │ TencentOS   │    │  TencentOS CVE  │
   │ Server      │    │  Database       │
   │ (本地/远程)  │    │  mirrors.       │
   │             │    │  tencent.com    │
   └─────────────┘    └─────────────────┘

📦 项目结构

tencentos-mcp-server/
├── pyproject.toml                    # 项目配置 & 依赖
├── Containerfile                     # 容器构建文件
├── README.md
├── LICENSE                           # Apache-2.0
├── mcp-config-example.json           # IDE MCP 配置示例
└── src/tencentos_mcp_server/
    ├── __init__.py
    ├── __main__.py                   # CLI 入口
    ├── server.py                     # FastMCP 实例 & 工具注册
    ├── executor.py                   # 命令执行抽象层
    ├── config.py                     # 配置管理
    ├── audit.py                      # 审计日志装饰器
    ├── models.py                     # Pydantic 数据模型
    ├── best_practices.py             # 调优最佳实践规则
    └── tools/
        ├── system_info.py            # 系统信息
        ├── processes.py              # 进程管理
        ├── services.py               # 服务状态
        ├── network.py                # 网络信息
        ├── storage.py                # 存储信息
        ├── logs.py                   # 日志查询
        ├── patch_impact.py           # ① 补丁影响评估
        ├── diagnostics.py            # ② 故障诊断
        ├── compliance.py             # ③ 合规举证
        ├── patch_history.py          # ④ 补丁版本管理
        └── system_tuning.py          # ⑤ 系统配置调优

🔑 环境变量

变量	说明	默认值
`TENCENTOS_MCP_TRANSPORT`	传输协议（stdio / sse / streamable-http）	`stdio`
`TENCENTOS_MCP_BIND_HOST`	SSE/HTTP 监听地址	`127.0.0.1`
`TENCENTOS_MCP_BIND_PORT`	SSE/HTTP 监听端口	`8000`
`TENCENTOS_MCP_API_KEY`	SSE/HTTP 模式的 Bearer Token 认证密钥	—
`TENCENTOS_MCP_HOST`	目标主机 IP（空 = 本地执行）	—
`TENCENTOS_MCP_USER`	SSH 用户名	`root`
`TENCENTOS_MCP_SSH_KEY_PATH`	SSH 私钥路径	`~/.ssh/id_rsa`
`TENCENTOS_MCP_SSH_PORT`	SSH 端口	`22`
`TENCENTOS_MCP_SSH_KNOWN_HOSTS`	SSH known_hosts（auto/none/路径）	`auto`
`TENCENTOS_MCP_AUDIT`	启用工具调用审计日志	`true`
`TENCENTOS_MCP_LOG_LEVEL`	日志级别	`INFO`

🔒 安全

设计原则

全只读：所有 26 个工具均标记 readOnlyHint=True，不执行任何修改操作
输入清理：所有用户输入参数经过白名单验证，防止命令注入
审计日志：每次工具调用自动记录（可通过 TENCENTOS_MCP_AUDIT 开关）
容器非 root：Containerfile 中以 mcp 用户运行

安全建议

场景	建议
本地开发	使用 stdio 模式，无需额外安全配置
内网部署	使用 SSE/HTTP + API Key，监听 `127.0.0.1`
公网暴露	⚠️ 强烈建议：反向代理 (nginx) + TLS + API Key

📄 协议

Apache License 2.0

🙏 致谢

Red Hat linux-mcp-server — 本项目的设计灵感来源
FastMCP — Python MCP 框架
TencentOS Server — 腾讯云自研服务器操作系统

from github.com/guoningzhang20/tencentos-mcp-server

Installing Tencentos

This server has no published package — it is built from source. Open the repository and follow its README.

▸ github.com/guoningzhang20/tencentos-mcp-server

FAQ

Is Tencentos MCP free?

Yes, Tencentos MCP is free — one-click install via Unyly at no cost.

Does Tencentos need an API key?

No, Tencentos runs without API keys or environment variables.

Is Tencentos hosted or self-hosted?

Self-hosted: the server runs locally on your machine via the install command above.

How do I install Tencentos in Claude Desktop, Claude Code or Cursor?

Open Tencentos on unyly.org, pick your client tab (Claude Desktop, Claude Code, Cursor) and press Install — the config is generated automatically, no JSON editing.

Related MCPs

GitHub

PRs, issues, code search, CI status

by GitHub

Filesystem

Secure file operations with configurable access controls.

by Community

Memory

Knowledge graph-based persistent memory system.