Agent MCP
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
Agent MCP
面向本地真实开发环境的跨平台 Agent MCP 服务端、子网关与控制台;让云端与本地大模型跨过沙盒玻璃墙,在受控边界内直接读写工程、驱动终端并调度工具链。
支持 Claude 暖纸风无边框桌面端(GUI)、1:1 全屏终端控制台(TUI)、同端口加密管理页(
/dashboard) 与 Rich 命令行 四端同源运行。
为什么做这件事
模型越训越聪明,却总像被关在防弹玻璃后面的参谋:能替你推演百行代码,却碰不到你硬盘上一行真实的工程;能写出漂亮的排障命令,却要由你充当人肉剪贴板,在聊天框与终端之间来回搬运报错与日志。各家客户端纷纷筑起自家的云端沙盒与专属插件,名为赋能,实则把算力、文件与工作流再一次拆成孤岛。
还有另一重荒诞:当你真想给模型接上十几个外部工具时,上百份冗长的 JSON Schema 在第一轮对话就塞满了上下文窗口——活还没干,注意力先被工具说明书耗去大半。
我们想把手脚还给模型,同时把缰绳留在自己手里:不绑死任何一家客户端,只按开放的 Model Context Protocol (MCP) 暴露能力;用外科手术式的原子编辑代替整文件覆写,用三枚极简元工具收拢整座子 MCP 生态,用多入口分流把公网隧道、OAuth 2.1 鉴权与目录白名单锁进清晰边界。门可以向远端敞开,但门栓永远握在你自己的机器上。
“我只能为你指明那扇门,走过去的路,得靠你自己。”
—— 莫菲斯,《黑客帝国》
Related MCP server: AKIMCP
捐赠
如果这个项目对你有帮助,欢迎自愿捐赠以示感谢。捐赠不构成任何支持承诺。
这是什么
Agent MCP 是基于 FastMCP 构建的本地系统级 MCP 宿主与聚合网关。无论客户端是网页端大模型(通过 Cloudflare Tunnel + OAuth 2.1 远程接入),还是本机 IDE / 桌面客户端(通过 HTTP、SSE 或 stdio 直连),所有请求都沿着同一条可观测、可热更新的链路流转:
AI Client (Gemini / Claude / Cursor / Antigravity / Custom Agent)
-> Transport (Streamable HTTP `/mcp` | SSE `/sse` | `stdio`)
-> Cloudflare Tunnel (Quick trycloudflare / Named Token) or Local Loopback
-> Multi-Profile Router (Host / Credential Matching -> Per-Entry Auth & AccessPolicy)
-> Secret & Scope Guard (Allowed Roots + Read-Only + `.env`/Key Protection)
-> Tool Execution
├─ Atomic Filesystem & Undo Stack
├─ Sync Command (UTF-8/GBK + Process-Tree Kill) & Async Background Daemons
└─ Sub-MCP Gateway (`list_sub_mcps` -> `inspect_sub_mcp` -> `call_sub_mcp`)
-> Live Structured Telemetry (`GuiController` -> Desktop GUI / Terminal TUI / `/dashboard`)核心设计取舍
1. 三元渐进发现,拒绝工具爆炸
传统网关把下游所有子 MCP 的工具一股脑平铺给模型,动辄上百个函数声明直接撑爆上下文并引发重名冲突。Agent MCP 的子网关始终只向主模型暴露 3 个元工具(list_sub_mcps、inspect_sub_mcp、call_sub_mcp):模型先看目录,需要哪个工具再按需拉取它的精确 inputSchema 并调用;配置增删改即时生效,无需重启主服务。
2. 同端口多入口(Profiles)与实时热加载
一个本地端口即可同时承载多套接入入口:你可以给主力云端助手开一条带 OAuth 2.1 与读写权限的固定域名隧道,给代码审查 Agent 开一条带 Bearer Key 且限定单目录只读的 Quick 临时隧道,再给本机脚本留一条回环直连。入口的启停、公网地址热注入与权限边界修改全部秒级热加载,不断连现有会话。
3. 外科手术式文件修改与单步反悔
模型直接重写大文件极易丢行或破坏缩进。内置 edit_file 强制要求原子级精确块匹配,匹配失败时自动计算并返回上下文近似行提示;配合 apply_patch(统一 Diff 补丁,支持 dry_run)、replace_text(多文件批量替换预览)以及内存快照栈驱动的 undo_edit,任何一次误改都能一键回滚。
4. 四端同源,不为无桌面环境妥协
无边框桌面控制台(
agent-mcp gui):Claude 暖羊皮纸与深色双主题(支持跟随系统)、自定义流畅缩放拖拽、系统托盘驻留。1:1 全屏终端控制台(
agent-mcp tui):基于Textual完整复刻桌面端三栏布局、活动调用卡片展开(含红绿 Diff 高亮)、子 MCP 探测与五张配置卡片,SSH 连上无头服务器也有完整图形化体验。同端口加密管理页(
/dashboard):无需额外开放管理端口,凭全局密码即可在任意浏览器远程管理。Rich 现代命令行(
agent-mcp run/config/profile/sub/tunnel):启动状态卡片与快捷子命令,兼顾脚本自动化与人类阅读体验。
内置工具矩阵(19 项)
所有工具均附带标准 MCP ToolAnnotations(区分只读、修改、破坏性与外部调用),并受当前入口 AccessPolicy 实时约束:
分类 | 工具名 | 权限级别 | 能力说明 |
目录与读取 |
| 只读 | 查看当前会话允许的根目录、工作目录与读写/密钥策略 |
| 只读 | 输出干净的目录树,自动跳过 | |
| 只读 | 读取大文件前预检字节大小、行数、预估 Token 数与类型 | |
| 只读 | 带行号与区间切片读取文本(自动兼容 UTF-8 / GBK 编码) | |
| 只读 | 单次批量读取多个文件,减少多轮往返延迟 | |
检索与定位 |
| 只读 | 按通配符高速匹配文件路径 |
| 只读 | 全文正则/字面量检索(优先调用 | |
原子编辑 |
| 写入 | 创建新文件(自动建父目录),覆盖已有文件需显式传 |
| 写入 | 原子级多处精确文本替换,失败时附带近似片段行号提示 | |
| 写入 | 应用标准 Unified Diff 补丁,支持 | |
| 写入 | 单文件或跨目录批量查找替换,支持 | |
| 写入/删除 | 安全移动、复制或删除文件与目录 | |
| 写入 | 撤销某路径最近一次创建、编辑、补丁或删除操作 | |
命令与进程 |
| 执行 | 同步执行命令(智能解码、首尾截断防刷屏、超时整棵进程树强杀) |
| 执行 | 启动长时后台进程(如本地开发服、编译监听、日志跟踪) | |
| 执行 | 列出后台进程、增量读取输出、写入 | |
子 MCP 网关 |
| 只读 | 列出已启用的嵌套子 MCP 服务摘要 |
| 只读 | 按需查看指定子 MCP 的工具清单或单个工具的完整参数 Schema | |
| 代理调用 | 向嵌套子 MCP 转发工具调用,参数错误时自动附带 Schema 纠错提示 |
环境要求
Python 3.10+
推荐(可选):系统安装
ripgrep(rg)以获得毫秒级代码搜索;未安装时会自动降级至纯 Python 实现。完整安装(
pip install -e ".[full]")包含桌面窗口(pywebview)、系统托盘(pystray+pillow)与全屏 TUI(textual);纯服务端仅依赖fastmcp。
安装与启动
git clone https://github.com/iamr0s/agent-mcp.git
cd agent-mcpWindows
安装脚本会自动准备虚拟环境、注册全局命令 agent-mcp / agent-mcp-gui,并写入桌面快捷方式与系统开始菜单(C:\ProgramData\Microsoft\Windows\Start Menu\Programs\Agent MCP.lnk):
# 推荐:以管理员或 Windows 11 sudo 运行(写入系统级开始菜单 + 桌面 + 用户 PATH)
sudo powershell -ExecutionPolicy Bypass -File .\scripts\install_windows.ps1
# 普通权限运行(自动回退至当前用户开始菜单 + 桌面)
powershell -ExecutionPolicy Bypass -File .\scripts\install_windows.ps1
# 也可直接双击 scripts\install_windows.bat
# 仅安装无头 CLI 服务端(跳过 GUI 依赖与快捷方式)
.\scripts\install_windows.ps1 -CliOnly
# 移除快捷方式(保留源码与本地配置)
sudo powershell -ExecutionPolicy Bypass -File .\scripts\install_windows.ps1 -UninstallLinux
自动创建 .venv、软链 CLI 至 ~/.local/bin、生成 XDG 桌面菜单项(~/.local/share/applications/agent-mcp.desktop),并支持注册 systemd --user 常驻服务:
chmod +x scripts/install_linux.sh
# 标准安装(CLI + 桌面应用菜单入口 + TUI)
./scripts/install_linux.sh
# 同时在桌面生成快捷图标
./scripts/install_linux.sh --desktop
# 无头服务器推荐:仅装核心依赖并启用 systemd 用户级后台自启
./scripts/install_linux.sh --cli-only --systemd
# 卸载快捷方式、软链与 systemd 单元
./scripts/install_linux.sh --uninstallmacOS
自动创建 .venv、软链 CLI 至 ~/.local/bin、生成原生 ~/Applications/Agent MCP.app 应用包(支持访达与聚焦搜索启动),并可选配置 launchd 自启:
chmod +x scripts/install_macos.sh
# 标准安装(CLI + ~/Applications/Agent MCP.app + TUI)
./scripts/install_macos.sh
# 无头常驻:仅装 CLI 并加载 LaunchAgent
./scripts/install_macos.sh --cli-only --launchd
# 卸载 .app、软链与 LaunchAgent
./scripts/install_macos.sh --uninstall手动安装(通用虚拟环境)
python -m venv .venv
# Windows: .venv\Scripts\activate
# Linux / macOS: source .venv/bin/activate
pip install -e ".[full]" # 完整安装(桌面 GUI + 全屏 TUI + 托盘)
pip install -e ".[tui]" # 服务端 + 全屏 TUI(适合远程服务器)
pip install -e . # 最简核心服务端交互形态与命令行用法
安装完成后,可在任意目录调用 agent-mcp(或在仓库根目录使用 python main.py):
# 1. 桌面无边框控制台(默认管理端口 8779)
agent-mcp gui
agent-mcp-gui
# 2. 全屏终端控制台(与桌面 GUI 1:1 对齐,SSH / 终端首选)
agent-mcp tui
# 3. 交互式向导与配置面板
agent-mcp setup # 终端分步引导配置
agent-mcp config # Rich 面板查看当前生效配置与入口列表
agent-mcp config --json # 输出脱敏 JSON(便于脚本读取)
# 4. 启动 MCP 服务(自动输出 Rich 状态卡片 + 实时彩色日志流)
agent-mcp run
# 5. 快捷运维子命令(与 GUI / TUI / Dashboard 实时共享配置)
agent-mcp profile list # 查看所有接入入口
agent-mcp profile enable <id> # 启用 / 停用 (disable) 指定入口
agent-mcp sub list # 查看嵌套子 MCP 列表与状态
agent-mcp sub inspect <name> # 实时探测子 MCP 暴露的工具清单
agent-mcp tunnel status # 查看或启停 (start / stop / stop-all) Cloudflared 隧道命令行参数覆盖与 stdio 接入
命令行参数优先级高于环境变量与 config/mcp_config.json:
# 临时指定双模监听、Bearer 鉴权与受限目录启动
agent-mcp run -t dual --host 127.0.0.1 -p 8000 --auth bearer --api-key sk-your-token -r /path/to/repo
# 纯只读安全审计模式(禁止一切写文件、删文件与命令执行)
agent-mcp run --read-only --allow-cwd
# 作为本地 stdio 子进程直接挂载到 Claude Desktop / Cursor / Antigravity
agent-mcp run -t stdio --allow-cwd也支持通过环境变量在容器或守护进程中注入配置:MCP_NAME、MCP_TOOL_PREFIX、MCP_TRANSPORT、MCP_HOST、MCP_PORT、MCP_AUTH_MODE、MCP_API_KEY、MCP_OAUTH_BASE_URL、MCP_OAUTH_CLIENT_ID、MCP_OAUTH_CLIENT_SECRET、MCP_LOG_LEVEL、MCP_LOG_FILE。
模块分层
agent-mcp/
├── main.py # 统一 CLI / GUI / TUI 启动入口
├── launch_gui.pyw # Windows 无控制台窗口静默启动器(含崩溃弹窗兜底)
├── agent_mcp/
│ ├── config.py # 存储布局、无损迁移、多 Profile 与敏感路径守卫
│ ├── server.py # FastMCP 组装、HTTP+SSE 双模路由、动态按请求策略注入
│ ├── auth.py # Bearer、本地自签发 OAuth 2.1、GitHub/Google/自定义 OIDC
│ ├── file_tools.py # 编码自适应读取、ripgrep 检索、原子替换、Diff 补丁与撤销栈
│ ├── process_tools.py # 进程树超时清理的同步命令与异步后台进程池
│ ├── sub_mcp.py # 嵌套子 MCP 连接池、Schema 探测与三元渐进代理
│ ├── tunnel.py # Cloudflared 在线安装/断点续传/本地导入与多隧道守护
│ ├── web_gui.py # GuiController 核心控制器与无边框桌面控制台
│ ├── tui.py # 与桌面端 1:1 对齐的 Textual 全屏终端控制台
│ ├── dashboard.py # 挂载于主服务端口 /dashboard 的密码保护远程管理页
│ ├── cli.py / cli_ui.py # 命令行路由、子命令与 Rich 终端面板
│ ├── tray.py # 跨平台系统托盘驻留
│ └── logging_utils.py # 结构化 JSON 事件总线与对齐彩色日志
├── scripts/ # Windows / Linux / macOS 安装、快捷方式与服务注册脚本
└── examples/ # 脱敏配置模板(mcp_config / mcp_sub_servers)安全边界与非目标
默认拦截敏感凭据:除非显式开启
allow_secrets,文件读写与搜索工具默认拒绝访问.env、私钥证书(*.pem、*.key、*.p12)以及 Agent MCP 自身的config/与data/状态文件,防止模型在排障时意外读取并外泄宿主机密钥。公网暴露必须设防:通过 Cloudflare Tunnel 将服务暴露至公网时,请始终启用
OAuth 2.1或高强度Bearer Key,并结合入口级目录白名单(roots)或只读开关(read_only)收敛权限。非沙盒虚拟化:本项目的目标是让模型操作真实的宿主机环境;在开启读写执行权限的入口下,
run_command拥有与当前操作系统用户同等的执行权限,请像对待 SSH 密钥一样保管你的授权凭据。运行态与代码严格分离:
config/*.json、data/、logs/、bin/cloudflared*与.env均已列入.gitignore,切勿强行提交至公开仓库。
许可
GNU General Public License v3.0,详见 LICENSE。
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Remote MCP server exposing your Node Command fleet (files, shell, processes, browser) to AI hosts.
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
MCP gateway and cloud hosting for MCP servers, agents and apps like RAG, managed from your agent.
Related MCP Servers
- FlicenseNot gradedqualityAmaintenanceExposes a governed suite of 38 tools over a single OAuth-gated MCP endpoint, letting web AI chat clients such as Claude, ChatGPT, and Grok operate on a local machine — reading and editing files, running whitelisted shell commands, searching, querying SQLite, driving browsers and DevTools, managing background jobs, ports, and clipboard. Local IDEs and Postman can also connect directly over localhost for offline, low-latency access.-
- AlicenseNot gradedqualityAmaintenanceEnables web-based AI clients like Claude, ChatGPT, and Grok to securely operate a local machine through OAuth-gated MCP tools covering files, shell, Git, databases, browser automation, and background tasks.MIT
- AlicenseNot gradedqualityAmaintenanceEnables web-based AI clients like Claude, ChatGPT, and Grok to securely operate a local machine through an OAuth-gated MCP endpoint, covering files, shell commands, search, Git, SQLite, browser automation, DevTools, background tasks, ports, clipboard, notifications, and Postman. Exposes 38 governed tools with a strict command whitelist, folder allowlisting, and rate limiting so browser chats can build projects, inspect databases and local APIs, and manage long-running jobs without granting unrestricted shell access.MIT
- AlicenseNot gradedqualityAmaintenanceEnables web AI clients and local IDEs to securely operate a local machine through an OAuth-gated MCP endpoint, with governed tools for files, shell, search, Git, SQLite, browser automation, DevTools, background tasks, localhost services, clipboard, notifications, ports, Postman, and AIObox windows.MIT