Skip to main content
Glama
Server Control MCP

Server Control MCP

by Gengetau

Server Control MCP

tests License: Apache-2.0

自托管的 Linux 服务器控制集成:让远程 MCP 客户端通过持久化 OAuth 调用文件、补丁、命令、终端会话、Git 和图片工具,并可订阅定向事件。

状态:0.1.0,首个提取版本。 目标平台 Linux / Python 3.11+。 执行核心来自 coding-tools-mcp 0.3.0,保持原样安装;本项目提供持久化认证网关、事件适配和部署集成。 不是上游官方发行版,也不是独立实现的执行引擎。

English · 部署 · 事件 · 安全边界 · 来源与差异

WARNING

本服务让通过认证的客户端在宿主机上远程执行命令、读写文件。仅供单一运维者使用; 只通过带速率限制的 HTTPS 入口公开 OAuth 网关,切勿公开执行端端口,切勿以 root 运行。 部署前请阅读 SECURITY.md。

环境要求

  • Linux,Python 3.11+(CI 覆盖 3.11 / 3.12 / 3.13)

  • 自己的 HTTPS 反向代理或隧道(本服务不签发 TLS 证书)

  • 可选:Docker Compose(Linux host 网络)或 systemd

Related MCP server: remote-access-mcp

提供什么

功能

实现来源

默认 18 项文件、命令、Git、图片及环境工具

上游 coding-tools-mcp

基础 MCP、OAuth/PKCE、动态客户端注册

上游

SQLite 保存注册、授权码、刷新授权

本项目扩展

刷新轮换、重放撤销、撤销接口

本项目扩展

定向事件、订阅持久化、签名回调与重试

本项目扩展,实验性、默认关闭

双进程监督、认证后端、systemd / Docker 示例

本项目集成

工具列表(上游 18 项)

类别

工具

环境

server_info、check_exec_environment、request_permissions

文件

read_file、list_dir、list_files、search_text、apply_patch

命令 / 终端

exec_command、write_stdin、read_output、kill_command

Git

git_status、git_diff、git_log、git_show、git_blame

图片

view_image

启用事件后,网关额外提供 server/discover 与 events/*(见下文)。

OAuth 只解决调用者认证;所有授权客户端仍共用一个操作系统账号和工作目录。 适用于自己管理的客户端,不用于互不信任的租户。

快速开始

以下命令在本项目根目录执行,使用普通用户:

python3 -m venv .venv
.venv/bin/python -m pip install .
.venv/bin/server-control-mcp init
mkdir -p workspace

编辑生成的 .env:将 CODING_TOOLS_MCP_SERVER_URL 改为自己的 HTTPS 源站地址, 例如 https://mcp.example.com,不加 /mcp;按需修改 SCM_WORKSPACE。 保留自动生成的密码和签名密钥,将 .env 放在工作目录之外。 该文件使用字面量 KEY=value 格式,不要加引号或 shell 表达式。

.venv/bin/server-control-mcp --env-file .env serve

默认执行端是 127.0.0.1:28766,OAuth 网关是 127.0.0.1:28767。 通过你自己的 HTTPS 反向代理或隧道将网关对外提供服务。 两者都不直接绑定公网。更完整的部署方法见 部署说明。

在支持远程 MCP OAuth 的客户端中添加:

https://mcp.example.com/mcp

使用生成配置里的专用密码登录。支持动态注册的客户端通常不需要预填 Client ID / Secret。 客户端是否支持令牌刷新、实验性 Events,取决于客户端自身;本版本没有逐个平台重新验收。

配置

init 生成的 .env 包含以下键(完整说明见 部署说明):

键

说明

CODING_TOOLS_MCP_SERVER_URL

必填,HTTPS origin,不带路径

CODING_TOOLS_MCP_OAUTH_PASSWORD / ..._TOKEN_SECRET

init 生成,至少 32 字符

CODING_TOOLS_MCP_OAUTH_TOKEN_TTL

访问令牌有效期,默认 3600 秒

SCM_STATE_DIR / SCM_WORKSPACE

私有状态目录 / 执行工作目录(二者不可嵌套)

SCM_BACKEND_PORT / SCM_GATEWAY_PORT

28766 / 28767,仅绑定 127.0.0.1

SCM_PERMISSION_MODE

safe(默认)/ trusted / dangerous

SCM_EVENTS_ENABLED

0(默认)/ 1

权限模式

由上游 coding-tools-mcp 0.3.0 执行:

模式

网络命令

shell 展开 / 内联脚本

Landlock(内核支持时)

过滤敏感环境变量

写全局 /tmp

跳过全部权限检查

safe(默认)

否

否

是

是

禁止

否

trusted

是

是

是

是

仅限前缀

否

dangerous

是

是

否

否

允许

是

dangerous 等同于以服务账号身份不受限执行,仅在隔离环境中使用。 实际生效情况请用 server_info / check_exec_environment 确认。

可选事件

设置 SCM_EVENTS_ENABLED=1 并重启后,支持实验性 MCP Events 的客户端可订阅 server.changed。本地业务系统按该客户端的 OAuth client_id 定向投递:

.venv/bin/server-control-mcp --env-file .env emit \
  --recipient YOUR_OAUTH_CLIENT_ID --kind task.assigned

回调只含事件编号、类型和时间,不含任务正文,也不代表任务已处理。 事件说明包含订阅格式、签名验证、去重和业务适配边界。

Docker 与 systemd

  • Linux Docker:.env 需在宿主机上生成(compose 会覆盖其中的状态与工作目录为命名卷):

    python3 -m venv .venv && .venv/bin/python -m pip install .
    .venv/bin/server-control-mcp init          # 生成 .env
    # 编辑 .env 中的 CODING_TOOLS_MCP_SERVER_URL
    docker compose up -d --build

    示例用普通容器用户(UID 10001)和命名卷,采用 Linux host 网络;HTTPS 入口仍由你配置。

  • 长期运行:参考 systemd 模板,调整目录后安装。

  • 不依赖任何特定云厂商、个人令牌或个人域名。

验证与打包

python -m unittest discover -s tests -v
python scripts/smoke.py
python scripts/release.py --check-only
python scripts/release.py

Smoke 在临时目录和随机端口启动真实执行端及网关,跑 OAuth 登录、文件与命令调用、 重启持久化、刷新与撤销;不会连接生产服务器或公开端口。 发布脚本按白名单创建源码 ZIP,拒绝常见凭据格式,并可从未纳入版本控制的本地 .release-denylist 文件读取额外正则(每行一个)。 验证结果和未覆盖部分见 VALIDATION.md。

许可证与来源

Apache-2.0,保留 LICENSE 和 NOTICE。上游执行包固定为 0.3.0,未复制其核心源码。 我们曾将它与官方 PyPI 发布 wheel 做逐文件比较,核心 15 个 Python 文件一致。 扩展提取来源和公开版改动见 provenance.md。

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Turns any Linux server into an AI-agent-accessible machine over HTTPS, allowing MCP clients like ChatGPT, Claude, and Grok to securely control files, run shell commands, inspect system state, query SQLite, and work with git behind a bearer token.
      76 npm
      4
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables MCP clients such as ChatGPT and Claude to administer Linux or macOS hosts through authenticated Streamable HTTP, including running shell commands, reading and writing files within a workspace, listing directories, and retrieving system metrics.
      1
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables managing Linux hosts and local coding agents from an MCP client through shell commands, files, background jobs, system information, instruction and skill discovery, and optional Claude Code, Codex, or Cursor CLI conversations. It provides privileged remote access with token authentication and can run longer work in the background.
      MIT