local-agent-mcp
Local Agent MCP
让 ChatGPT Pro 直接在你的本地电脑上干活
你在 ChatGPT 里交代任务,它就能调用本机 MCP 工具:读取项目、修改文件、运行测试、检查 Git Diff、创建 Commit。
复杂任务可以交给本地 Codex。ChatGPT 继续负责拆分步骤、查看进度、补充要求和最终检查。
ChatGPT Pro
→ Local Agent MCP
→ 本地文件 / 测试 / Git / Codex不需要反复复制代码,也不需要让每个任务都绕到 Codex。
这是非官方社区项目。它不是 OpenAI 产品,也不代表 OpenAI。
Related MCP server: chatgpt-codex-tools-mcp
快速开始
前提条件
准备好以下内容:
macOS 或 Linux
Python 3.11 及以上
Git
OpenAI 官方
tunnel-client支持自定义 MCP App 的 ChatGPT 环境
一个 Tunnel ID
一个对应的 Tunnel Runtime Key
macOS 可以先安装基础工具:
brew install uv tmux
brew install openai/tools/tunnel-client一句话交给 AI
把这句话发给一个能操作本机终端的 AI:
把 https://github.com/ezra-y/local-agent-mcp 安装到我的电脑上,并按照 README 完成配置、启动和验证。
手动安装见:安装到 ChatGPT。
亮点
亮点 | 说明 |
ChatGPT 直接操作本地项目 | 常见文件、测试和 Git 操作由 ChatGPT 直接调用本机工具完成。 |
ChatGPT 负责总指挥 | 简单任务直接完成,复杂任务可以交给本地 Codex。 |
Agent 可以继续扩展 | Codex 是第一个 Adapter;后续 Agent 放进同一套控制层。 |
任务状态可查询 | Workflow、Step、Job 保存到本地 SQLite,重启后仍可查看。 |
防止重复执行 | 相同的 |
Git 过程清楚 | 先查看状态和 Diff,再提交明确列出的文件;不会自动 Push。 |
权限透明 | Tool 和 Resource 都可以返回当前权限资料。 |
28 个工具
类别 | 工具 | 用途 |
权限 |
| 查看当前根目录、硬限制和高权限入口。 |
文件 |
| 列出、读取、创建、覆盖或局部修改文本文件。 |
命令与测试 |
| 运行命令或测试,并查看或停止后台 Job。 |
Git |
| 查看状态、查看 Diff、提交明确列出的文件;安全 Commit 会关闭 Hook 和签名,并拒绝 Git Filter。 |
工作流程 |
| 建立 Workflow、创建 Step、启动 Job、查询整体状态。 |
一次性只读 Codex |
| 让本地 Codex 做一次只读检查。 |
Codex 线程 / 回合 |
| 读取旧 Thread,启动、继续、补充、停止和检查 Codex Turn。 |
健康检查 |
| 查看服务状态、活动 Job 数和 Artifact 容量警告。 |
直接的 delete_file Tool 没有暴露。apply_patch 也拒绝删除整个文件。
git_commit 默认关闭仓库 Hook 和提交签名。检测到 clean / process Git Filter 时会拒绝提交,避免结构化 Commit 隐式运行仓库程序。git_diff 同时关闭外部 Diff 和 textconv。
权限 Resource
除了 get_permissions Tool,服务还提供:
local-agent://permissions内容包括:
当前允许访问哪里
哪些目录和文件被禁止
读写是否开启
有没有直接删除工具
高权限入口有哪些get_permissions 会继续保留,方便尚未展示 MCP Resources 的客户端使用。
权限与减权
默认范围
结构化文件和 Git 工具默认可以访问当前用户的 Home:
$HOME通常包括 Desktop、Downloads、Documents 和个人目录下的其他项目。
代码强制禁止的内容
结构化文件工具会拒绝:
.ssh
.aws
.azure
.codex
.docker
.gnupg
.kube
.Trash
Library
.env 和 .env.*
常见凭据文件
.pem / .key / .p12 / .pfx 私钥文件
符号链接路径同时:
没有直接文件删除 Tool。
apply_patch不能删除整个文件。没有 Git Push Tool。
git_commit只提交明确列出的路径。
缩小结构化范围
启动前设置:
export LOCAL_AGENT_MCP_ROOT="$HOME/Projects"旧配置名 CODEX_MCP_ROOT 仍然兼容。
之后这些工具只能访问 $HOME/Projects:
list_files
read_file
write_file
apply_patch
git_status
git_diff
git_commit前台启动示例:
export LOCAL_AGENT_MCP_ROOT="$HOME/Projects"
./scripts/run_tunnel.sh高权限入口
能力 | 实际范围 |
| 会执行项目代码。测试代码可以创建、修改或删除文件。 |
| 被调用的本机程序可能访问结构化根目录之外的位置。 |
完整 Codex Turn | 可以读写、运行命令和联网,也可能访问结构化根目录之外的位置。 |
LOCAL_AGENT_MCP_ROOT 是结构化文件与 Git 工具的硬边界,不是整个进程的系统沙箱。
需要仓库 Hook、Git LFS 或其他 Filter 时,请手动提交,或在明确检查仓库配置后使用高权限的 run_command。
v0.5.1 暂时没有按单个 Tool 隐藏或关闭的配置。需要更强隔离时,可以使用独立系统用户、虚拟机、容器,或维护删减 Tool 的版本。
完整说明见 docs/permissions.md。
安装到 ChatGPT
1. 下载并测试
git clone https://github.com/ezra-y/local-agent-mcp.git
cd local-agent-mcp
uv sync --locked --all-groups
uv run pytest -q本地 Codex 的查找顺序:
CODEX_BIN指定的路径。PATH中的codex。macOS ChatGPT App 内置的 Codex。
2. 保存 Runtime Key
macOS:
./scripts/save_tunnel_key.shLinux:
export CONTROL_PLANE_API_KEY="<你的 Runtime Key>"3. 生成 Tunnel 配置
export CONTROL_PLANE_TUNNEL_ID="tunnel_<32位小写十六进制>"
./scripts/configure_tunnel.sh本地配置保存在:
.runtime/profiles/4. 启动 Tunnel
前台:
./scripts/run_tunnel.sh后台:
tmux new-session -d \
-s local-agent-mcp-tunnel \
-c "$PWD" \
./scripts/run_tunnel.sh等待服务就绪:
for i in {1..30}; do
curl -fsS http://127.0.0.1:8741/readyz && break
sleep 1
done成功时返回:
ready本地状态页:
http://127.0.0.1:8741/ui5. 在 ChatGPT 中连接
打开 Settings → Apps。
开启 Developer Mode。
创建或连接对应的自定义 MCP App。
Tunnel 启动后,点击 Refresh / Scan tools。
新开聊天并选择
@Local Agent。
6. 验证
在新聊天发送:
@Local Agent
调用 get_permissions。
报告当前工具总数、版本和 allowed_root。v0.5.1 的预期结果:
工具总数:28
版本:0.5.1
allowed_root:你的 Home,或你设置的 LOCAL_AGENT_MCP_ROOT客户端支持 Resources 时,再尝试读取:
local-agent://permissions只运行本地 stdio MCP
不使用 ChatGPT Tunnel 时:
./scripts/run_mcp.sh也可以安装成全局命令:
uv tool install .
local-agent-mcp旧命令 local-codex-mcp 仍然可用。
日常使用
工具中的 project 参数通常填写相对 $HOME 的路径:
Documents/Codex/local-agent-mcp
Downloads/my-project
Desktop/example-projectHome 内的绝对路径也支持。project="." 代表整个结构化根目录;默认设置下就是整个 Home。
一个常用任务
@Local Agent
在 Downloads/my-project 修复登录失败问题。
检查相关代码和 Git 状态,完成修改、测试、Diff 和 Commit。常见流程:
get_permissions
→ git_status / list_files / read_file
→ write_file / apply_patch
→ run_tests
→ git_diff
→ git_commit复杂任务可以再加入显式 Workflow 或本地 Codex。
Workflow 怎么运行
五个概念
概念 | 含义 |
Workflow | 用户交代的整件事。 |
Step | Workflow 中一个稳定、明确的动作。 |
Job | 某个 Step 的一次实际执行。 |
Codex Thread | Codex 保存的聊天和工作上下文。 |
Codex Turn | Thread 中的一轮工作。 |
执行顺序
create_workflow
→ create_step
→ start_step
→ get_job / get_workflowcreate_step 当前支持四种执行类型:
| 用途 |
| 运行测试。 |
| 运行参数数组形式的本机命令。 |
| 让 Codex 做一次只读检查。 |
| 启动一个持续工作的 Codex Turn。 |
文件读取和修改仍由 read_file、write_file、apply_patch 直接完成。
示例:创建测试 Step
create_workflow(
project="Downloads/my-project",
title="验证登录修复"
)
→ workflow_idcreate_step(
workflow_id=workflow_id,
position=1,
name="运行测试",
executor_kind="tests",
spec={
"argv": ["uv", "run", "pytest", "-q"],
"cwd": ".",
"timeout_seconds": 900
},
write_scope="worktree"
)
→ step_idstart_step(
workflow_id=workflow_id,
step_id=step_id,
attempt=1
)
→ job_idget_job(job_id)
get_workflow(workflow_id)执行身份是:
workflow_id + step_id + attempt相同编号再次启动,会返回原 Job,不会重复执行。明确重跑时使用新的 attempt,例如 attempt=2。
并行规则
同一个 Codex Thread:同一时间一个活动 Turn
同一个 Worktree:同一时间一个写入者
同一个仓库:不同 Worktree 可以并行活动 Turn 需要补充要求时使用 steer_codex_turn,需要停止时使用 interrupt_codex_turn。
本地状态和日志
源码运行时:
.runtime/state.sqlite3
.runtime/artifacts/<job_id>/安装后的命令默认使用:
$HOME/.local/state/local-agent-mcp/state.sqlite3自定义位置:
export LOCAL_AGENT_MCP_STATE_PATH="/自定义位置/state.sqlite3"旧配置名 CODEX_WORKFLOW_STATE_PATH 仍然兼容。已有旧状态库也会继续读取。
长日志放在 Artifact 文件中。SQLite 保存路径、大小和 SHA-256。
Artifact 不会自动删除。记录总量超过 1 GiB 时,ping 会返回警告。
更新
git pull
uv sync --locked --all-groups
uv run pytest -q然后重启 Tunnel,并在 ChatGPT 中点击 Refresh / Scan tools。
项目结构
src/local_agent_mcp/
├── server.py MCP 入口与公共 Tool / Resource
├── adapters/ 本地 Agent Adapter;当前包含 Codex
├── workflow_*.py Workflow、Step、Job、锁和 SQLite
├── command_jobs.py 后台命令与测试
├── workspace_tools.py 文件读写与 Patch
└── git_tools.py Git 状态、Diff 和 Commit
tests/ 单元测试与集成测试
docs/ 权限和架构说明
scripts/ MCP 与 Tunnel 启动脚本测试文件会保留在仓库中。它们用于验证权限边界、跨平台运行、打包和兼容性;安装后的 wheel 只包含运行代码。
开发检查
uv run pytest -q
uv run python scripts/check_public_release.py
zsh -n scripts/*.sh
uv build主 MCP 入口是 src/local_agent_mcp/server.py。src/codex_bridge.py 作为旧导入和旧启动方式的兼容别名保留。
卸载和本地数据
卸载程序不会自动删除 SQLite、Artifact、Tunnel profile 或源码目录。请先检查并决定哪些数据需要保留。
License
MIT,见 LICENSE。
⚠️ 默认配置会开放较大的本地权限:ChatGPT 可读写当前用户 Home 下的大多数项目,并可运行测试、命令和本地 Agent;请只在你信任的电脑、账号和项目中使用。
Available Tools
28 toolsapply_patchApply project patchBDestructive
Apply an authorized Begin Patch block transactionally.
Inputs: patch (required), project (required). Returns: result
ask_codexAsk local CodexARead-only
Start a read-only local Codex job and return its job ID immediately.
The project is a path relative to the configured Codex root. The server rejects paths outside that root and always runs Codex in read-only mode. Use get_codex_job to retrieve the final result.
Inputs: prompt (required), attempt, project, step_id, +1 more. Returns: result
cancel_codex_jobCancel local Codex jobBIdempotent
Cancel a local Codex job; force only releases unconfirmed state.
Inputs: job_id (required), force. Returns: result
cancel_jobCancel command jobCDestructiveIdempotent
Cancel a unified job; force only releases unconfirmed state.
Inputs: job_id (required), force. Returns: result
create_stepCreate workflow stepCIdempotent
Create an immutable executable Step inside one Workflow.
Inputs: name (required), spec (required), position (required), workflow_id (required), +3 more. Returns: result
create_workflowCreate workflowB
Create a durable Workflow for a multi-Step task.
Inputs: title (required), project (required), metadata. Returns: result
get_codex_jobGet local Codex jobBRead-onlyIdempotent
Get the status and result of a local Codex job.
Inputs: job_id (required). Returns: result
get_codex_turn_statusGet local Codex turn statusARead-onlyIdempotent
Get status, items, and final agent message for one Codex turn.
Inputs: turn_id (required), thread_id (required). Returns: result
get_jobGet command jobARead-onlyIdempotent
Get unified command, test, Codex, or Codex Turn job status.
Inputs: job_id (required). Returns: result
get_permissionsGet effective permissionsARead-onlyIdempotent
Return the effective root, hard boundaries, and tool-use policy.
Inputs: no named parameters. Returns: result
get_workflowGet workflowBRead-onlyIdempotent
Get a durable Workflow with its Steps and Job attempts.
Inputs: workflow_id (required). Returns: result
git_commitCreate Git commitBDestructive
Commit authorized paths without hooks, signing, filters, or pushing.
Inputs: paths (required), message (required), project (required). Returns: result
git_diffGet Git diffARead-onlyIdempotent
Return a bounded workspace or staged diff and its stat.
Inputs: project (required), path, scope. Returns: result
git_statusGet Git statusARead-onlyIdempotent
Return branch, HEAD, modified, staged, and untracked files.
Inputs: project (required). Returns: result
interrupt_codex_turnInterrupt local Codex turnCDestructiveIdempotent
Interrupt an active local Codex turn.
Inputs: turn_id (required), thread_id (required). Returns: result
list_codex_threadsList local Codex threadsBRead-onlyIdempotent
List local Codex app-server threads, optionally filtered by project.
Inputs: limit, cursor, project, archived, +1 more. Returns: result
list_filesList project filesARead-onlyIdempotent
List readable files in a project under the configured structured root.
Set include_all to true to include dependencies, runtime state, Git internals, and caches. Credential files and credential directories are always excluded. Paths are relative to the selected project.
Inputs: project, include_all. Returns: result
pingCheck local MCP bridgeARead-onlyIdempotent
Return bridge process health without accessing project files.
Inputs: no named parameters. Returns: result
read_codex_threadRead local Codex threadBRead-onlyIdempotent
Read thread metadata and a bounded, paginated page of turns.
Inputs: thread_id (required), cursor, turn_limit, include_turns. Returns: result
read_fileRead project fileARead-onlyIdempotent
Read one UTF-8 text file from a selected project.
Both the project and file path are constrained to the configured root. Common credential files and credential directories are excluded; Git files, dependencies, and runtime configuration are readable.
Inputs: path (required), project (required). Returns: result
resume_codex_threadResume local Codex threadADestructive
Load an existing local Codex thread with unattended full access.
This is a high-privilege entry point. Use it only after explicit user authorization under the permission policy returned by get_permissions.
Inputs: thread_id (required), project. Returns: result
run_commandRun project commandADestructive
Start an argv-based command job and return its ID immediately.
This is a high-privilege entry point. No shell is inserted, but the chosen executable can access paths outside the structured root. Use it only under the explicit policy returned by get_permissions. Use get_job for output and cancel_job to stop it.
Inputs: argv (required), project (required), cwd, attempt, +3 more. Returns: result
run_testsRun project testsADestructive
Start authorized project tests as a background job.
Test code can create files and execute project-controlled code.
Inputs: project (required), cwd, argv, attempt, +4 more. Returns: result
start_codex_jobStart local Codex jobCRead-only
Start a read-only Codex inspection job and return immediately.
Inputs: prompt (required), attempt, project, step_id, +1 more. Returns: result
start_codex_turnStart local Codex turnADestructive
Start a persistent app-server turn and return its IDs immediately.
Omit thread_id to create a new local Codex thread. Poll with get_codex_turn_status; the turn continues after this MCP call returns. This is a high-privilege entry point and may access paths outside the structured tool root.
Inputs: prompt (required), model, effort, attempt, +4 more. Returns: result
start_stepStart workflow stepAIdempotent
Start one explicit Step attempt or return its existing Job.
Inputs: attempt (required), step_id (required), workflow_id (required). Returns: result
steer_codex_turnSteer local Codex turnBDestructive
Send additional instructions to an authorized active Codex turn.
Inputs: prompt (required), turn_id (required), thread_id (required). Returns: result
write_fileWrite project fileCDestructiveIdempotent
Create or replace one UTF-8 file after explicit user authorization.
Inputs: path (required), content (required), project (required). Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 28 tools
Several tools have near-identical purposes: ask_codex and start_codex_job both start read-only Codex jobs, and get_codex_job/cancel_codex_job duplicate functionality already covered by the unified get_job/cancel_job. The distinction between Codex jobs, Codex turns, and workflows is also fuzzy, making selection error-prone.
Most tools follow verb_noun snake_case (e.g., list_files, cancel_job), but there are inconsistencies: 'ask_codex' uses an unconventional verb, 'ping' is a bare noun, and the mix of ask/start/steer/intrerupt for Codex operations lacks a clear pattern. Still, the majority are consistent enough to be readable.
With 28 tools, the surface is heavy, especially given the redundant job/turn management tools. Several tools could be merged or eliminated (e.g., ask_codex/start_codex_job, get_codex_job/get_job), suggesting the count is inflated beyond what the domain requires.
The surface covers core local agent operations well: file read/write/patch/list, git status/diff/commit, command and test execution, workflow management, and Codex interactions (jobs, turns, threads). Minor gaps exist (no delete file or git push), but the main workflows are supported.
Related MCP Connectors
Use your Mac, Windows or Linux computer from ChatGPT, Claude or Codex: files, commands, documents.
Work on your own computers from Claude or ChatGPT: run commands, edit and search files.
Connect ChatGPT, Claude, Cursor or VS Code to your Windows PC: files, terminal, browser, apps.
Project memory, documentation and controlled secret access for AI coding agents.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceEnables ChatGPT to remotely orchestrate local Codex and Claude Code agents for file editing and command execution via a secure Cloudflare tunnel, bridging cloud AI planning with local execution.1MIT
- AlicenseNot gradedqualityBmaintenanceEnables ChatGPT to inspect and edit local projects through a secure MCP interface, offering workspace management, file operations, git integration, and safe command execution.6MIT
- AlicenseNot gradedqualityCmaintenanceBridges ChatGPT with local computer for controlled file and project management, featuring session-based collaboration and diff tracking.4Apache 2.0
- AlicenseNot gradedqualityDmaintenanceEnables ChatGPT to securely control a local workstation via an MCP tunnel, exposing 44 tools for file/project editing, git, process supervision, browser automation, and Office document handling across macOS, Linux, and Windows.7MIT