claudeaibridge

给 claude.ai —— 包括免费版 —— 在你自己的机器上带来真正的编程代理体验：文件编辑、shell 访问、git，全部在你明确选择的项目文件夹中完成，且完全由网页驱动。不需要 IDE，不需要 Claude Code 订阅，也不需要手动把代码复制粘贴到浏览器里。

它的原理是：运行一个本地小服务器，该服务器支持 MCP（与 Claude Code 和 Claude Desktop 用于工具时相同的协议），通过公共 URL（经 ngrok，或你自己的域名/隧道）将其作为自定义连接器暴露给 claude.ai，并用一道真实的 OAuth 授权界面把控访问权限——只有你，在这台机器上，才能批准。

为什么

claude.ai 连接器本来就已经让 Claude 通过远程 MCP 服务器读写其他服务（Google Drive、GitHub 等）中的数据。本项目就是把同样的机制指向你自己的文件系统——也就是 Claude Code 在本地做的事，只不过改成了从浏览器标签页触达。

Related MCP server: claude-agent-mcp

如何保护安全

这相当于给一个网页在你电脑上编辑文件、运行 shell 命令的能力。设计上严重地倾向于隔离（containment）而非信任：

• 你选择文件夹。 连接器永远只能看到你在这台机器上（通过 CLI）明确注册过的项目文件夹——它自己没有任何办法新增一个，因此连接器 URL 泄露并不等于“可以访问你整个磁盘”。

• 文件系统隔离。 每个文件工具在写入磁盘之前，都会把路径解析出来、对照当前项目的根目录进行检查；../ 穿越和符号链接逃逸都会被拒绝。shell 命令在沙箱中运行（Linux 用 bwrap，macOS 用 sandbox-exec），沙箱让其余文件系统全部变成只读。

• 真实的 OAuth 授权。 连接不是走形式——claude.ai 必须走完一套 OAuth 流程，这个流程会在这台机器上打开一个页，明确列出已经注册了哪些项目，并且必须由用户点击 Approve。不会静默授予任何东西。

• 可撤销安全性。 文件编辑在改任何东西之前都会保留备份；删除时并不移除文件，而是把文件移到本地废纸篓文件夹中；两者都发生在项目自己的 .claudeaibridge/ 文件夹内。

• 审计轨迹。 每次文件/脚本操作都以纯文本形式追加到 <project>/.claudeaibridge/audit.log——任何时候都能回答：“Claude 在这里到底做了什么？”

交互式 widget

在支持它的主机上，file_write 和 file_edit 会把它们的变更直接渲染在聊天里，成为彩色的逐行 diff——自动完成，不需要任何额外步骤。它默认展开；点击那个文件名就能折叠或展开。无论怎样，Claude 拿到的结果数据都完全一样（改了哪些内容、备份路径、错误详情）——widget 只是把同一数据可视化渲染出来，而不是替代品。在不支持 widget 的主机上，这个工具原本的普通结果也不会受到影响。

平台支持

支持 Linux 和 macOS。Windows 暂不支持（沙箱方案还没有对应的 Windows 实现）。

安装

选项 1 —— 用 PyInstaller 自行构建预编译二进制. （见 从源码构建）——目前没有单独的下载步骤，仍只是构建步。

选项 2 —— 从源码运行，需要 Python 3.10+：

git clone https://github.com/yemi-sh/claudeaibridge.git
cd claudeaibridge
python3 -m venv .venv
.venv/bin/pip install -e .

快速开始

claudeaibridge init

它会一步步带你完成所有步骤：

1. 获取一个 ngrok authtoken（免费——[点这里获取](https://dashboard.ngrok.com/start /your-authtoken)），或者已有自己的域名/隧道，或者只要本地测试。

2. 通过交互式选择器为 claude.ai 选择项目文件夹（方向键导航、空格选择、输入即可过滤查找）。

3. 把自己安装成后台服务（Linux 用 systemd，macOS 用 launchd），并打印出连接器 URL——之后你可以关闭终端，它会继续运行。

然后，在 claude.ai 中：设置 → 连接器 → 添加自定义连接器，粘贴打印出来的 URL。claude.ai 会打开一个浏览器标签页进行授权——在授权页上点击批准——而后就连接上了。让 Claude 列出当前可用的项目，选一个，然后开始工作吧。

在 claudeaibridge status 上，随时查看状态。如果没有可用服务管理器（比如 Windows，或是没有 systemd 用户会话的 Linux 环境），init 就会回退到前台运行时。

命令参考

claudeaibridge init

上面描述过的交互式设置向导。可以随时重跑——每一步都会显示出你已配置的选项，并决定保留还是修改。重新运行会用你本次的选择重新安装后台服务，替换掉旧的。

claudeaibridge status

显示后台服务当前是否在运行，以及它最后打印出的连接器 URL。

claudeaibridge stop

停止后台服务并不再安装使用（完全移除 systemd/launchd 单元，而不只是停止服务）——连接器会离线，直到你再次运行 init 或 serve。

项目（Projects）

claudeaibridge add-project ~/code/my-repo   # register a specific folder
claudeaibridge add-project                  # or pick one (or several) interactively
claudeaibridge edit-project ~/code/my-repo  # unregister that folder directly
claudeaibridge edit-project                 # or open the picker, pre-checked with
                                             # everything registered — check/uncheck
                                             # to add or remove
claudeaibridge list-projects                # print all registered paths

项目的身份就是它在文件系统中解析出的最终路径，全部由它自己解析。若不这样，Claude 会记得住它——它没有要专门记住的名字，所谓不存在单独的名称可以记忆。

claudeaibridge serve

用你给它的参数把 MCP 服务器安装/启动为后台服务（init 在向导最后也会调进同一条路径），然后返回——不会阻塞你的终端。如果后台服务已经在运行，serve 会直接给出连接器 URL，而不会再重新安装。

示例：

claudeaibridge serve --ngrok                                    # install+start as a service
claudeaibridge serve --base-url https://your-domain.example     # bring your own tunnel
claudeaibridge serve --no-auth --foreground                     # local-only testing, blocking
claudeaibridge serve --transport stdio                          # local MCP client

claudeaibridge ngrok

claudeaibridge ngrok set-authtoken <token>   # one-time setup
claudeaibridge ngrok status                  # check whether a token is configured

每个 ngrok 账户（包含 Free tier）都会拥有一个固定域名，它会在授权后自动绑定这个域名，并且只靠 authtoken 即可，你不用再配置其他任何东西。如果你在用付费套餐，也想用自定义域名，那么你只要自己跑一个 ngrok http --domain=... 服务，并用 --base-url 指到 claudeaibridge serve（不传 --ngrok）即可。

配置

所有的都放在 ~/.config/claudeaibridge/ （或 $XDG_CONFIG_HOME/claudeaibridge）下：

• projects.json — 已获授权的项目白名单。

• ngrok_authtoken — 你的 ngrok token (chmod 600)

• oauth_state.json — 已经注册的 OAuth 客户端和令牌，让 claude.ai 中批准连接器的批准只需要一次，而不是每次重启都重新授权。

• connector_url — 服务器最后打印的 URL，好让你在后台服务运行、其 stdout 没有人在看的时候，claudeaibridge status 仍能显示，不至于什么都没有。

从源码构建

pip install -e '.[build]'
./packaging/build.sh

生成 dist/claudeaibridge-<os>-<arch>。PyInstaller 不能跨平台编译——它只能为“现在就运行（所在）的平台”构建。

运行测试

pip install -e '.[test]'
python tests/smoke_test.py        # core MCP tools, in-memory
python tests/oauth_flow_test.py   # full OAuth flow against a real subprocess
python tests/tunnel_test.py       # live ngrok test — needs NGROK_AUTHTOKEN set

已知限制

• 不支持 Windows，且 init 的后台服务步骤需要使用 systemd（Linux）或 launchd（macOS）——二者都没有的话会回退到前台运行。

• 后台用的 launchd（macOS）路径已实现但还没有验证——它只在 Linux（systemd）上构建并测试过，因为那套开发环境里只有该平台可用。

• 目前只有一个 widget：file_write/file_edit 会以带颜色的 diff 形式展示自身的变更。这个已经与 claude.ai 上实时验证可用。

License

GPL-3.0-or-later。