Skip to main content
Glama

nexus-mcp

给云端 AI(Gemini 自定义 MCP、ChatGPT 连接器)用的本地 MCP 服务,暴露 9 个工具: read / write / edit / bash / glob / grep / job_start / job_output / job_kill。

装在 Windows 上,只监听 127.0.0.1,外面通过 cloudflared 隧道访问;隧道进程由自带控制面板启停和守护。

装上就能用

本地跑一次 npm run package,产物落在 release/ 下,两个随便挑一个:

  • nexus-mcp_0.1.0_x64-setup.exe —— 安装包。双击,装到当前用户目录(不弹 UAC),装完桌面和开始菜单有快捷方式,卸载走「设置 → 应用」。

  • nexus-mcp-0.1.0-win64.zip —— 绿色版。解压到任意目录就能用。

三步上手:

  1. 双击桌面上的 nexus-mcp(或解压目录里的 启动.cmd),控制面板会在浏览器里打开。

  2. 面板「连接信息」里直接显示云端要填的 MCP 地址和令牌,点「复制地址+令牌」一次带走 (首次启动自动生成,同时打印在启动窗口里)。

  3. 云端填地址:Gemini 会跳到 OAuth 授权页,输入面板上的令牌批准即可; ChatGPT 连接器等能自定义请求头的客户端用 Bearer 鉴权(Authorization: Bearer <令牌>)。 两条路并存,详见下面「鉴权」。

首次启动会在程序目录生成 config.json 和 workspace/(默认沙箱根)。卸载不会删这两个。

bash 与 job_* 需要机器上有 Git Bash(Git for Windows);read / write / edit / glob / grep 不依赖任何外部命令。grep 首次使用会下载一份固定版本的 ripgrep 到全局缓存。

Related MCP server: AKIMCP

鉴权

token 非空时两条路都开着:服务先比对静态 Bearer,不匹配再验 OAuth 2.1。

  • OAuth 2.1(Gemini 走这条):连接器填 https://<隧道域名>/mcp 后自动发现授权端点, 浏览器打开授权页,输入 config.json 里的令牌批准即可。动态注册的客户端与 refresh token 落盘在 config.json 旁的 oauth-store.json,删掉它等于吊销所有已授权客户端。

  • 静态 Bearer:能自定义请求头的客户端都能用,令牌就是面板上显示的那个。

token 为空时服务不校验任何请求,仅限本机调试,别配着隧道用。

控制面板

面板独立监听 8788(panelPort,默认 port + 1),停服务时面板不掉线:

  • 三盏状态灯:执行器 / MCP 服务 / 隧道。隧道灯只看 cloudflared 的本地就绪连接数, 不看公网往返(为什么,见 docs/tunnel.md)。

  • 服务按钮:停止 / 启动 / 重启 / 重载配置。

  • 连接信息卡:MCP 地址、令牌显示与复制,外加 OAuth 授权入口。

  • 隧道卡(配了 tunnel 段才有):公网地址、启动 / 停止隧道、检测可达性 (真实请求公网 /health,只影响这条显示,不影响灯)、pid 与日志尾行。

  • 根目录选择,保存即生效;可用工具卡(9 个);最近 100 行日志。

隧道

  • 服务在 MCP 端口上提供无鉴权的 GET /health,只报存活,可从公网访问。

  • 配置 tunnel 段后面板接管 cloudflared:进程异常退出 10 秒后自动拉回 (tunnel.autoRestart: false 关闭);面板「停止隧道」不触发守护,想停就停得住。

  • 命令行兜底 nexus-tunnel.cmd:服务挂死时用它手动拉起;服务活着时 nexus-tunnel stop 会被守护 10 秒拉回,真停隧道走面板按钮。现行运维记录都在 docs/tunnel.md。

开机自启(可选)

安装包和绿色版都不会加开机自启。要的话,在 %APPDATA%\Microsoft\Windows\Start Menu\Programs\Startup 放一个 nexus-mcp.vbs:

Set sh = CreateObject("WScript.Shell")
sh.CurrentDirectory = "C:\Users\<你>\AppData\Local\Programs\nexus-mcp"
sh.Run """C:\Users\<你>\AppData\Local\Programs\nexus-mcp\nexus-mcp.exe""", 0, False

结尾的 0 是隐藏窗口,False 是不等它退出。

cloudflared 另有自己的一份开机自启(启动文件夹里的 nexus-tunnel.vbs),跟这份脚本互不相干。 隧道守护跟随服务进程——服务没起时,隧道靠它自己的自启活着。现状见 docs/tunnel.md。

卸载程序不会删这个文件(它只认自己装的东西)。卸载后记得手动删掉,否则每次开机都会弹一次找不到 exe 的报错。

升级 / 换版本

  1. 先确认 8787 上没人监听:Get-NetTCPConnection -LocalPort 8787 -State Listen。 有输出说明还有旧进程,用 OwningProcess 那一列的 pid 结束它:Stop-Process -Id <pid>。

  2. 双击新的安装包装上。覆盖安装会自己 taskkill 掉 nexus-mcp.exe 和 nexus-executor.exe, 但杀不掉开发态起的 node dist/index.js——端口冲突就是这么来的。

  3. 重新启动服务。

装完启动报 EADDRINUSE: address already in use 127.0.0.1:8787,就是第 1 步没清干净。

配置

优先级:环境变量 > 程序目录的 config.json > 内置默认。

环境变量

对应 config.json 字段

说明

NEXUS_MCP_CONFIG

—

指定配置文件位置,直接顶掉程序目录的 config.json

NEXUS_MCP_TOKEN

token

Bearer 令牌

NEXUS_MCP_ROOT

root

沙箱根目录,越界访问直接报错

NEXUS_MCP_PORT

port

MCP 端口,panelPort 未配时取 port + 1

只存在于 config.json 的常用字段:

字段

默认

说明

transport

http

stdio 给本机客户端;打包版 exe 加 --stdio 参数可无视配置强制 stdio

shell

auto

bash / job_* 用的 shell,默认自动找 Git Bash,可指明 pwsh(PowerShell 7);powershell(5.1)启动即报错

commandPolicy

空

命令白/黑名单,见「命令闸门」

tunnelUrl

—

隧道公网地址,配了面板才会去探测连通性

tunnel

—

cloudflared 管理段(路径 / 守护开关 / metrics 端口),配了面板才提供隧道启停

maxOutputBytes / defaultTimeoutMs

64KB / 120s

单工具输出上限 / 单条命令默认超时

字段全表与校验规则见 src/config.ts。

命令闸门

bash 与 job_start 里的每条命令在 spawn 前过闸门(crates/executor/src/command_policy.rs), 两个工具共用同一套判定与话术。三层判定顺序固定,任一子命令被拒则整条命令拒绝:

  1. 内置危险表——无条件生效,不依赖用户配置,开箱即拦:

    • rm 同时带递归(-r/-R/--recursive)与强制(-f/--force)标记(仅 git-bash);

    • format、diskpart、reg delete;

    • cmd /c 内部的 del/erase 带 /f、rd/rmdir 带 /s /q(黏连运算符如 echo hi&del 会切开判定);

    • pwsh 下删除 cmdlet(Remove-Item 及别名 rm/ri/del/erase/rd/rmdir)与 -Force 同段出现; 显式 pwsh -Command "..." 包裹时,任何 shell 下都检查脚本内容。

    拒绝话术附命中规则、原因与替代做法,可直接贴给模型。

  2. 黑名单 commandPolicy.deny:通配模式,任一子命令命中即拒。

  3. 白名单 commandPolicy.allow:通配模式,非空即启用;每条子命令都必须命中, 没接住的按 onUnmatched 处理(默认 deny,改 "allow" 可放宽)。

"commandPolicy": {
  "allow": ["git *", "npm run *", "cargo *"],
  "deny": ["git push --force*"],
  "onUnmatched": "deny"
}

判定前的解析规则:

  • 顶层 ; && || | & 把命令拆成简单命令段,逐段判定;

  • $( )、反引号、进程替换、双引号内的替换体递归检查一层;sudo/env 前导与 VAR=value 赋值剥离后再判;trap 的 action 当 shell 源码递归;

  • fail-closed:引号/括号/反引号未闭合、命令名含变量或替换(首词带 $)、wrapper 嵌套 超过 8 层,一律拒绝,不猜。

匹配细节:白/黑名单的匹配目标是「归一化后的可执行名 + 其余参数原样」——首词剥路径与盘符、 ASCII 小写、去掉 .exe/.cmd/.bat/.com 后缀。模式里 * 匹配任意序列(含空格)、 ? 匹配单字符,\ 与 / 等价,Windows 下大小写不敏感;模式以 " *" 结尾时裸命令 (不带参数)也命中。

已知局限(字面判定哲学):只看命令字面量,看不见变量展开后的实际内容(动态命令名因此直接 fail-closed);管道把数据喂给危险命令(如 cat list | xargs rm)这类数据流不在字面判定范围内。

闸门不绕沙箱:越出 root 的文件访问一律报错,不静默裁剪。

分发

打包机需要 Rust 与 Node 24;目标机器什么都不用装。

npm run package        # 约 25 秒:esbuild 打 CJS → SEA 注入 → zip → NSIS 安装包
npm run package:smoke  # 拿刚出的产物在最小环境里自检:启动、连上、read、面板

产物落在 release/(不进版本库),文件名里的版本号取自 package.json:

文件

说明

nexus-mcp_<版本>_x64-setup.exe

NSIS 安装包,按用户装到 %LOCALAPPDATA%\Programs\nexus-mcp,桌面 + 开始菜单快捷方式,卸载入口进「应用和功能」

nexus-mcp-<版本>-win64.zip

绿色版,四个文件平铺:nexus-mcp.exe、nexus-executor.exe、启动.cmd、使用说明.txt

发给别人之前要知道的:

  1. 都没有签名,SmartScreen 首次会拦一次(「更多信息 → 仍要运行」),企业策略可能直接拦掉。要正经发就得买代码签名证书。

  2. 两个 exe 必须在同一目录:nexus-mcp.exe 找不到 nexus-executor.exe 时,只有文件类工具能用,报错里会指出缺哪个文件。

  3. 覆盖安装会先 taskkill 掉正在跑的 nexus-mcp.exe / nexus-executor.exe(杀不掉开发态的 node dist/index.js,见「升级 / 换版本」);卸载只删程序文件,config.json、workspace 和你自己加的开机自启脚本都留着。

  4. 第一次打包要联网取 NSIS 3.11(2.4MB,脚本里钉了 SHA-256 校验);内网机器可以用 NEXUS_NSIS_DIR 指向已解压的 NSIS 目录跳过下载。

  5. 默认 MCP 端口 8787、面板 8788;目标机器上被占了就改 config.json 的 port / panelPort。

开发

npm run build        # cargo build --release 构建执行器,再 tsc
npm run typecheck
npm run test         # vitest,只走 MCP 客户端入口
npm run test:rs      # Rust 侧
npm run smoke        # 起服务、列出工具、调一次 read
npm run check        # build + vitest + cargo test + smoke,提交前必须全绿
npm run package      # 出 release/ 下的 zip 与 NSIS 安装包
npm run package:smoke # 在最小环境下验证打包产物(启动、连上、read、面板)

目录:src/ TypeScript 侧(MCP 协议、工具、HTTP、面板、执行器客户端)、crates/executor/ Rust 执行器、 scripts/ 自检与打包、docs/research/ 调研笔记。

动手前读 AGENTS.md(命令、禁忌、踩过的坑),调研结论在 docs/research/。

致谢

  • Nexus 项目——本项目脱胎于它:上上游 ysunyang4/Nexus、 上游 shixian64/Nexus。OAuth 桥接层自其 apps/bridge/src/oauth.ts 移植而来,因此本仓库整体以 AGPL-3.0 发布(见 LICENSE 与 NOTICE);工具层按「少而清楚」重写。

  • opencode(MIT)——edit 的三级匹配、命令闸门的通配匹配、 ripgrep 的发现与调用组合从它移植;明细见 NOTICE 与 docs/research/opencode-reusable-parts.md。

  • codex(Apache-2.0)——输出有界缓冲、UTF-8 边界截断、 命令策略的危险规则与可执行名归一化来自它;明细见 NOTICE 与 docs/research/codex-reusable-parts.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
      Enables AI clients to securely control and interact with a local Windows machine through 218 configurable tools for files, Git, processes, Windows UI, browser automation, WSL, Office, recovery, skills, and child MCP servers.
      MIT
    • F
      license
      Not graded
      quality
      A
      maintenance
      Exposes a governed suite of 38 tools over a single OAuth-gated MCP endpoint, letting web-based AI clients such as Claude, ChatGPT, and Grok read and edit files, run whitelisted shell commands, search, query SQLite, use Git, automate browsers and DevTools, manage background tasks, reach localhost services, and control the clipboard, notifications, ports, and Postman. This turns remote AI chats into secure operators of a local machine without granting unrestricted shell access.
      -
    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables 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
    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables 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