aimcp

让 Gemini CLI 或 ChatGPT 通过 MCP 操作你电脑上的代码项目。

安装并连接后，你可以在 Gemini CLI 或 ChatGPT 里直接说：

• “先看看这个项目是做什么的”

• “检查一下现在有哪些改动”

• “修掉这个报错”

• “跑一下测试”

• “把这个功能实现完”

• “切到另一个项目继续”

aimcp 会在你的电脑上读取文件、修改代码、执行命令、查看 Git，并把结果返回给 MCP 客户端。

为了减少模型选择工具时的歧义，多项目 daemon 只公开 15 个顶层工具：project_control 加上 read、read_image、apply_patch、ls、grep、glob、code_explore、exec_command、write_stdin、skills_list、skill_read、mcp_tools、mcp_call、summary。Git 和包管理等操作统一通过 exec_command 完成。

aimcp 面向个人开发环境使用。它拥有很强的本机操作能力，请只连接你信任的 MCP 客户端和项目。

它是怎么工作的？

aimcp 把本机控制面和真正处理 MCP 请求的 Runtime 分开：

Web Console / CLI
       │
       ▼
本机 Controller ─── 项目、配置、日志、诊断、更新
       │
       ▼
MCP Runtime ─────── 工具执行、OAuth、项目运行态
       │
       ▼
Cloudflare Tunnel 或你自己的 HTTPS 入口
       │
       ▼
ChatGPT 或 Gemini CLI

Controller 只监听本机，负责管理状态；Runtime 可以启动或停止。aimcp stop 只停止 Runtime，所以 Web Console 仍然能打开并用于修复配置；aimcp shutdown 才会把两者都关闭。

所有注册项目共享 一个 MCP Runtime。aimcp project add 只注册项目，不会隐式启动 Runtime；aimcp start 会先注册当前项目，再按保存的运行模式启动 Runtime。

每个 MCP 会话只会绑定一个项目。这样你可以在不同会话里分别处理不同项目，也可以明确切换当前会话使用的项目。ChatGPT 会提供稳定的对话级 session 标识；Gemini CLI 等 MCP 客户端通过独立的 MCP session 隔离绑定。

Related MCP server: AgentDock

你需要准备什么？

必需

• Node.js 22 或更高版本

推荐

• Git：用于查看状态、提交历史和差异

如果要从 ChatGPT 连接

你需要一个可以通过 HTTPS 访问到本机 aimcp 的公网地址。

最简单的方式是：

• 一个 Cloudflare 账号

• 一个已经接入 Cloudflare 的 域名

aimcp 可以自动创建和管理 Cloudflare Tunnel。

如果你已经有自己的反向代理、服务器或其他 HTTPS 入口，也可以不让 aimcp 管理 Cloudflare。

可选

如果电脑上已经安装了这些工具，aimcp 还可以读取它们已有的能力：

• Codex

• Claude Code

• Agent Skills

没有这些也不影响 aimcp 的核心功能。

快速开始

1. 安装

安装全局 aimcp 命令：

npm install --global @rookiedj/aimcp

检查安装：

aimcp --version

如果终端提示找不到 aimcp，请确认 npm 的全局可执行目录在 PATH 中；可用 npm config get prefix 查看全局安装前缀，然后重新打开终端。

从源码运行时，在仓库根目录执行 npm install、npm run build，再运行 npm run start:local。

2. 打开 Web Console（推荐）

运行：

aimcp open

这只会启动本机 Controller 并打开 Web Console，不会启动 MCP Runtime，也不会自动修改公网配置。

推荐按这个顺序使用：

1. 在“项目”里添加 MCP 客户端可以操作的目录

2. 如果要从远程 MCP 客户端连接，在“连接”里按“公网地址 → 连接密码 → 检查连接”三步完成配置

3. 回到“概览”，明确选择“启动公网服务”或“仅本机启动”

4. Codex / Claude / Skills、诊断、日志和更新统一放在“系统”里

如果你更喜欢终端，也可以完全不用 Web：

aimcp project add /path/to/project
aimcp setup        # 只有需要远程 MCP 连接时才需要
aimcp start

公网连接

默认情况下，aimcp 会询问是否自动配置 Cloudflare Tunnel。

选择自动配置后，它会：

1. 准备 cloudflared

2. 打开浏览器登录 Cloudflare

3. 读取账号中的域名

4. 让你选择一个域名

5. 创建或复用当前电脑对应的 Tunnel

6. candidate 准备完成前保持现有后台服务在线；只有实际切换时才短暂停止

7. 启动 candidate connector，确认它已经连接 Cloudflare

8. 保存原 DNS 记录，再把域名切换到 candidate Tunnel

9. 在默认最多 5 分钟的兜底窗口内验证公网随机探针确实回到这台电脑；可随时 Ctrl+C 安全取消

10. 验证成功后才原子提交本机配置；失败会恢复 DNS，并保留上一次可用配置

例如最终得到：

https://aimcp.example.com/mcp

如果你的 Cloudflare 账号里没有已经接入 Cloudflare 的域名，自动 Tunnel 模式无法完成配置。

Cloudflare Tunnel 生成的 <UUID>.cfargotunnel.com 是 DNS CNAME 目标，不是直接给 MCP 客户端使用的地址。

使用自己的 HTTPS 入口

如果你不想让 aimcp 管理 Cloudflare，可以在 setup 中选择自己提供公网入口，然后填写你的域名。

此时需要你自己保证：

https://你的域名/mcp

能够安全地转发到本机 aimcp 服务。

连接密码

公网验证完成后，aimcp 会先生成远程 MCP 连接密码。

请保存这个密码。

电脑上只保存密码哈希，不保存明文密码。忘记以后不能找回，只能重新设置。

重新设置密码：

aimcp auth

外部能力（可选）

核心公网连接和连接密码完成后，setup 还会检测当前环境是否存在：

• Codex

• Claude Code

• Agent Skills

你可以选择：

• 使用检测到的全部能力

• 自定义启用哪些 MCP / Skills

• 全部关闭

默认推荐自动同步。这样这些工具的配置发生变化后，aimcp 可以自动刷新。当前目录没有检测到某个能力源，不会再把用户之前为其它项目启用的同类能力全局关闭；取消这一步也不会破坏已经完成的公网连接和连接密码。

3. 用 CLI 启动项目

进入项目目录：

cd /path/to/your-project
aimcp start

start 的顺序是：先注册当前项目，再启动/复用 Controller，最后启动 Runtime。这样即使公网配置有问题，项目注册也不会丢，CLI 会给出 Web Console 地址供你继续修复。

如果还没有配置公网连接，裸 aimcp start 默认使用本机模式。显式运行 aimcp start --local 也会把本机模式保存为以后默认；公网模式同样会保存，下次裸 start 会复用实际运行模式。

同一个项目以后再次运行不会创建第二套服务器，只会刷新项目状态并确保共享 Runtime 可用。

你也可以从其他目录指定项目：

aimcp start --root /path/to/your-project

查看当前状态：

aimcp status

你会看到：

• Controller 是否运行、Web Console 地址

• MCP Runtime 是否运行，以及当前/默认运行模式

• 本机 MCP 地址

• 公网 MCP 地址

• Cloudflare Tunnel 是否在线

• 当前 CLI 版本和正在运行的 daemon 版本

• 两者版本不一致时的 aimcp restart 提示

• 已注册项目

• 每个项目当前有多少会话绑定

4. 连接 ChatGPT

ChatGPT 的 MCP App 入口和可用套餐可能会变化，请以你当前账号的 Apps 设置为准。

当前常见流程是：

1. 在 ChatGPT 中启用 Developer Mode

2. 打开 Apps → Create

3. 填入 aimcp 的 MCP 地址

4. 扫描工具（Scan Tools）

5. 按提示完成 OAuth / 密码验证

6. 创建并启用这个 App

MCP 地址就是 setup 最后显示的公网地址，例如：

https://aimcp.example.com/mcp

授权时使用 aimcp setup 生成的连接密码。

连接完成后，就可以直接让 ChatGPT 操作本机项目。

完整 MCP 写入能力是否可用取决于 ChatGPT 当前的套餐、工作区权限和产品开放状态。如果你的设置里没有 Developer Mode 或创建自定义 MCP App 的入口，请先确认当前 ChatGPT 账号是否支持。

5. 连接 Gemini CLI

Gemini CLI 支持通过 HTTP 连接 MCP 服务。

在项目目录中启动本机服务：

npm run start:local

然后把本机 MCP 服务注册到 Gemini CLI 的用户配置：

gemini mcp add --scope user --transport http aimcp http://127.0.0.1:3920/mcp
gemini mcp list

确认显示 Connected 后，重启 Gemini CLI；进入会话后运行 /mcp 查看工具。本机模式只允许同一台电脑上的客户端访问，不需要连接密码。端口 3920 是默认值；如果修改过服务端口，注册时同步替换地址。使用公网地址时，把地址换成 https://你的域名/mcp 并以公网模式启动；Gemini CLI 会按 OAuth 流程提示授权，连接密码可通过 aimcp setup 创建或用 aimcp auth 修改。

更多配置选项见 Gemini CLI MCP 文档。

6. 连接 Gemini 应用（网页版）

Gemini 网页应用可以通过“已连接的应用”连接 aimcp 的自定义 MCP。这个流程与 Gemini CLI 的 gemini mcp add 不同。

准备公网 MCP 地址

Gemini 应用需要访问公网 HTTPS 地址；127.0.0.1 只对本机有效，不能填入 Gemini 应用。

cd /path/to/your-project
aimcp setup           # 尚未配置公网入口时运行
aimcp start --public
aimcp status          # 复制“公网地址”，例如 https://aimcp.example.com/mcp

如果已经配置好公网入口，只需确保 Runtime 以公网模式运行，再从 aimcp status 复制地址。setup 会显示连接密码；忘记密码时可运行 aimcp auth 重新设置。

在 Gemini 应用中添加

1. 在电脑上打开 Gemini 网页应用，进入 设置 → 个性化智能服务 → 已连接的应用。

2. 在“自定义应用”中选择添加应用，并粘贴 aimcp status 显示的公网 MCP 地址。

3. 按页面提示继续；在 aimcp 授权页输入连接密码并确认授权。

4. 回到 Gemini 对话，输入 @ 并选择 aimcp，然后提出请求。需要时先说“切换到 <项目名> 项目”。

自定义应用需从 Gemini 网页版添加；连接后可在网页版和手机应用中使用。Google 当前列出的条件包括：年满 18 岁、位于美国、使用个人 Google 账号、开启“活动记录”，且界面目前仅支持英文。若看不到“已连接的应用”或“自定义应用”，请查看 Google 官方说明及可用条件。

aimcp 可读取和修改已注册项目中的文件并执行命令。只注册你信任并希望交给 Gemini 操作的项目；公网连接密码不要分享给他人。

多项目怎么用？

这是当前版本最重要的使用方式。

先区分两个概念：

• 注册项目（Registered Project）：通过 Web Console、aimcp project add 或 aimcp start 注册的项目。一个 MCP 会话同一时间只绑定一个注册项目。

• 会话绑定（Conversation Binding）：MCP 会话当前选择的注册项目；文件和命令工具只能在这个项目目录内运行。

项目注册由本机 Controller/CLI 完成；模型只通过 project_control 选择已经注册的项目，不会自行注册项目或扩大路径边界。

注册多个项目

假设电脑上有三个项目：

~/code/api
~/code/web
~/code/mobile

分别进入目录运行：

cd ~/code/api
aimcp start

cd ~/code/web
aimcp start

cd ~/code/mobile
aimcp start

它们会全部注册到同一个 aimcp 后台服务。

不会创建三个端口，也不会创建三个 Tunnel。

查看所有项目：

aimcp project list

也可以显式注册指定目录：

aimcp project add /path/to/project

查看单个项目详情：

aimcp project info <项目 ID、项目名或目录>

MCP 会话会绑定一个项目

一个 MCP 会话只操作一个项目。

例如你可以说：

使用 web 项目，看看首页现在有什么问题。

MCP 客户端会通过 project_control 选择对应项目，然后后面的文件读取、代码修改、命令执行和 Git 操作都会以这个项目为上下文。

另一个独立的 MCP 会话可以同时绑定 api 项目，互不影响。

如果要在当前对话切换项目，可以直接说：

切换到 api 项目。

切换已有绑定时需要明确确认，不会静默跳到另一个项目。

如果某些旧会话不再需要保留项目绑定，可以在 Web Console 的“项目”页面逐个或全部清除，也可以在终端运行：

aimcp bindings clean [项目]

终端会列出该项目的会话编号；只会清理你显式选中的绑定。清理不会删除客户端会话或项目文件，这些会话下次使用项目工具时需要重新选择项目。

停止一个项目

推荐使用：

aimcp project remove <项目 ID、项目名或目录>

如果当前终端就在项目目录，也可以省略目标：

aimcp project remove

这只会停用目标项目；后台服务、Cloudflare Tunnel 和其他项目仍然继续运行。重新启用时，再运行 aimcp start 或 aimcp project add <目录>。

停止或重启后台服务

停止：

aimcp stop

重启：

aimcp restart

stop 只关闭 MCP Runtime、项目运行态和 Cloudflare Tunnel，Controller / Web Console 继续运行，项目注册状态也会保留。restart 只重启当前 Runtime，并保持当前运行模式。

如果要把 aimcp 的 Controller 和 Runtime 都完全关闭：

aimcp shutdown

MCP 客户端可以做什么？

连接项目以后，MCP 客户端可以通过 aimcp：

读取和搜索代码

• 读取单个或多个文件

• 搜索字符串和正则表达式

• 按文件模式查找文件

• 浏览目录

• 查找代码关系

修改代码

• 使用事务式 apply_patch 精确替换已有代码

• 批量创建、覆盖或删除文件

• 提交失败时自动回滚本次批量改动

执行命令

• 运行构建

• 运行测试

• 安装依赖

• 启动开发服务器

• 管理长时间运行的进程

Git

• 通过 exec_command 使用项目现有的 Git CLI

项目切换

当你说：

继续这个项目。

或者：

先看看这个项目现在是什么情况。

客户端会先用 project_control 查看并绑定一个已注册项目，再通过精简工具集读取代码、Skills 和命令结果。一个 MCP 会话同一时间只绑定一个项目。

项目路径边界

所有文件工具和命令工作目录都限制在当前绑定项目的主目录内。

当前项目

运行：

cd ~/code/my-project
aimcp start

那么：

~/code/my-project

就是这个项目的主工作区。

相对路径默认都从这里开始。

访问其他目录

需要处理另一个目录时，把它注册成独立项目：

aimcp project add /path/to/other-project

然后让 MCP 客户端使用 project_control 明确切换。工具不会通过绝对路径绕过当前项目边界。

路径限制不是完整的操作系统沙箱。项目内启动的 shell 命令仍然拥有当前系统用户本身拥有的系统权限。

使用 Codex、Claude Code 和 Skills

aimcp 可以直接读取已有 AI 开发工具的配置，而不是复制一份。

支持：

常见位置包括：

~/.codex/
~/.claude/
~/.agents/skills/

Claude Code 项目内的 .claude/skills 也可以按项目读取。

这些能力默认只是读取和引用原配置，不会把第三方 Token、MCP 配置和 Skill 文件复制到 ~/.codex-mcp。

重新管理这些设置：

aimcp setup

然后选择：

管理外部能力

支持两种同步方式：

• watch：配置发生变化后自动刷新，推荐

• startup：只在 aimcp 启动时读取一次

常用命令

再次运行 setup 会发生什么？

已经完成首次配置后，再运行：

aimcp setup

不会重新走一遍所有步骤。

你可以选择：

• 检查当前配置

• 修改公网连接

• 重新登录 / 切换 Cloudflare 账号

• 修改连接密码

• 管理 Codex / Claude Code / Agent Skills

• 退出，不做修改

“检查当前配置”会真实验证公网地址是否能够连接回当前电脑，而不只是检查配置文件是否存在。 这个检查只读取已提交配置和运行状态，不会登录 Cloudflare、修改 DNS 或重写 Tunnel 配置。

修改公网连接时，如果后台服务正在运行，setup 会先保留它的完整运行参数和所有项目注册，安全停止后完成切换，再按原参数恢复。多项目和会话绑定文件不会被重置。

配置保存在哪里？

aimcp 的用户数据默认保存在：

目录名沿用旧版，以便现有项目、连接密码和 Tunnel 配置在升级后继续使用。

~/.codex-mcp/

主要文件包括：

~/.codex-mcp/config.json
~/.codex-mcp/controller.json
~/.codex-mcp/daemon.json
~/.codex-mcp/projects.json
~/.codex-mcp/session-bindings.json
~/.codex-mcp/logs/

其中：

• config.json：监听地址、公网连接、外部能力、客户端工具策略和 UI 设置

• controller.json：仅本机 Controller 的 PID、loopback 端口和随机控制凭据；Web Console 由它提供

• daemon.json：当前 MCP Runtime 状态；执行 stop 后会移除，而 Controller 继续运行

• projects.json：注册过的项目

• session-bindings.json：MCP 会话和项目的绑定关系

Cloudflare 的登录和 Tunnel 凭据由 aimcp 放在自己的配置目录中管理，不依赖系统级 ~/.cloudflared 作为长期运行状态。

日志

运行日志位于：

~/.codex-mcp/logs/

结构化日志文件类似：

codex-mcp.2026-08-12.0.jsonl

Cloudflare Tunnel 原始日志：

~/.codex-mcp/logs/tunnel.log

正常的工具日志不会记录：

• 原始命令内容

• 文件内容

• 工具返回的完整内容

• OAuth 凭据

它主要记录工具名、耗时、结果状态等运行信息。

如果遇到启动、Tunnel 或 MCP 连接问题，首先查看这里。

检查问题

运行：

aimcp doctor

它会检查：

• Node.js 版本

• Git

• 文件搜索组件

• aimcp 配置

• 连接密码

• 公网地址

• cloudflared

• Cloudflare 登录

• Tunnel 凭据

• Tunnel 配置文件

• 外部能力设置

这是排查问题时最先应该运行的命令。

如果文件搜索组件缺失，可以直接运行：

aimcp doctor --fix

它会下载项目固定版本的受管 ripgrep，校验 SHA-256，并在安装后重新验证版本；不需要重新执行整套安装脚本。

常见问题

aimcp 命令找不到

重新打开终端后再试。

如果仍然找不到，重新运行安装脚本。

ChatGPT 连接不上

先运行：

aimcp status
aimcp doctor

确认：

• 后台服务正在运行

• 公网连接已启动

• 公网地址正确

• Tunnel 没有报错

再查看：

~/.codex-mcp/logs/

忘记连接密码

密码明文无法找回。

重新设置：

aimcp auth

Cloudflare 登录错了账号

运行：

aimcp setup

选择：

重新登录 / 切换 Cloudflare 账号

aimcp 会在临时目录完成新登录并验证凭据，然后才替换自己管理的登录；取消或登录失败时旧凭据保持不变。它不会修改系统级 ~/.cloudflared。

Cloudflare 上有旧 Tunnel，配置对不上

重新运行：

aimcp setup

aimcp 会检查本机 Tunnel 凭据和 Cloudflare 上的 Tunnel 是否匹配。

如果发现同名 Tunnel 但本机没有可用凭据，不会删除远端 Tunnel，而是创建带唯一后缀的 candidate。只有本次新建、配置尚未提交且没有被 DNS 引用的 candidate 才会自动清理。

Tunnel 一直连接不上

查看：

~/.codex-mcp/logs/tunnel.log

某些网络或防火墙会阻止 Cloudflare Tunnel 使用的 TCP 7844 连接。

当前版本会优先使用 IPv4，并在连接超时时给出更具体的错误提示。

ChatGPT 看不到新的精简工具列表

先在 ChatGPT 的 MCP / App 设置中执行 Refresh，或者重新发布 / 重新连接当前 MCP App。

工具 ABI 已精简为固定的 15 个入口。旧的 ChatGPT action snapshot 不再兼容已删除的工具，因此升级后必须让 ChatGPT 重新扫描工具。

我需要每个项目启动一个 aimcp 吗？

不需要。

每个项目只需要运行一次：

aimcp start

用来把它注册到同一个后台服务。

真正运行的 MCP server 和 Cloudflare Tunnel 都只有一套。

关闭终端以后 aimcp 会停吗？

默认不会。

正常的 aimcp start 会启动后台守护进程，终端命令完成后服务继续运行。

查看：

aimcp status

停止后台服务：

aimcp stop

更新

1.0 干净基线

1.0 是一次 breaking release，不读取旧版命令、旧版配置字段或旧 OAuth 状态。升级前请用已安装的旧版 CLI 停止服务，备份 ~/.codex-mcp，再移走其中的 config.json、oauth-state.json、daemon.json、projects.json 和 session-bindings.json，然后重新运行：

aimcp setup

请保留托管组件、连接密码和 Cloudflare 凭据。重新 setup 会选择新的已提交配置；旧 OAuth 会话与项目绑定不会恢复，项目需要重新注册。不要删除整个 ~/.codex-mcp，其中保存 aimcp 的本机配置和连接数据。

旧的 tunnel、exit 和 serve --foreground 入口已删除；分别使用 setup、stop / project remove 和后台 start。

aimcp update

1.0 之后的常规更新会保留配置和连接密码；从旧版首次升级仍须完成上面的基线重置。

更新后运行：

aimcp restart

这样可以确保正在运行的 daemon 使用当前 CLI 版本。aimcp status 会同时显示 CLI 和 daemon 版本；如果两者不一致，会直接提示重启。

卸载

如果是通过本项目的 npm link 安装的：

npm unlink -g @rookiedj/aimcp

此操作只移除全局命令，不会删除用户配置和连接密码。

如果你确定不再使用，并希望彻底删除所有状态，可以再手动删除：

~/.codex-mcp

安全说明

aimcp 的目标不是做一个强隔离沙箱，而是让受信任的 MCP 客户端可以在个人开发环境中完成开发工作。

因此请注意：

1. 不要把自己的 aimcp 实例分享给其他人。

2. 不要把连接密码公开。

3. 只注册你信任的项目目录。

4. 执行 shell 命令时，命令仍拥有当前系统用户本身的权限。

5. 如果电脑上保存了生产环境密钥、SSH Key 或其他敏感文件，请按照正常本机开发安全标准管理它们。

公网 MCP 入口需要连接密码认证，但它不能替代操作系统级隔离。

高级说明：ChatGPT 工具列表兼容

正常情况下你不需要关心这一节。

ChatGPT 有时会缓存已经批准过的 MCP action 列表。当前工具 ABI 是固定的 15 个入口，升级后请在 ChatGPT 中 Refresh MCP App 或重新发布连接，让旧的 action snapshot 被完整替换。项目选择统一使用 project_control，其他已删除工具没有兼容别名。

本地开发

克隆项目后：

npm ci
npm run typecheck
npm run build

开发模式：

npm run dev

只在本机调试：

npm run dev:once -- --local

发布版本要求 Node.js 22。日常 CI 和发版验收都会在 Linux、macOS、Windows 上运行类型检查、完整测试和真实 tarball 隔离安装 smoke；发布流程只分发已经通过 smoke 的同一个 tarball artifact。

License

MIT