Skip to main content
Glama
local-agent-mcp
by ezra-y

Local Agent MCP

English · 权限说明 · 架构说明

让 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

  • uv

  • 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,重启后仍可查看。

防止重复执行

相同的 workflow_id + step_id + attempt 会返回原 Job。

Git 过程清楚

先查看状态和 Diff,再提交明确列出的文件;不会自动 Push。

权限透明

Tool 和 Resource 都可以返回当前权限资料。

28 个工具

类别

工具

用途

权限

get_permissions

查看当前根目录、硬限制和高权限入口。

文件

list_files、read_file、write_file、apply_patch

列出、读取、创建、覆盖或局部修改文本文件。

命令与测试

run_command、run_tests、get_job、cancel_job

运行命令或测试,并查看或停止后台 Job。

Git

git_status、git_diff、git_commit

查看状态、查看 Diff、提交明确列出的文件;安全 Commit 会关闭 Hook 和签名,并拒绝 Git Filter。

工作流程

create_workflow、create_step、start_step、get_workflow

建立 Workflow、创建 Step、启动 Job、查询整体状态。

一次性只读 Codex

ask_codex、start_codex_job、get_codex_job、cancel_codex_job

让本地 Codex 做一次只读检查。

Codex 线程 / 回合

list_codex_threads、read_codex_thread、resume_codex_thread、start_codex_turn、steer_codex_turn、interrupt_codex_turn、get_codex_turn_status

读取旧 Thread,启动、继续、补充、停止和检查 Codex Turn。

健康检查

ping

查看服务状态、活动 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

高权限入口

能力

实际范围

run_tests

会执行项目代码。测试代码可以创建、修改或删除文件。

run_command

被调用的本机程序可能访问结构化根目录之外的位置。

完整 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 的查找顺序:

  1. CODEX_BIN 指定的路径。

  2. PATH 中的 codex。

  3. macOS ChatGPT App 内置的 Codex。

2. 保存 Runtime Key

macOS:

./scripts/save_tunnel_key.sh

Linux:

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/ui

5. 在 ChatGPT 中连接

  1. 打开 Settings → Apps。

  2. 开启 Developer Mode。

  3. 创建或连接对应的自定义 MCP App。

  4. Tunnel 启动后,点击 Refresh / Scan tools。

  5. 新开聊天并选择 @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-project

Home 内的绝对路径也支持。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_workflow

create_step 当前支持四种执行类型:

executor_kind

用途

tests

运行测试。

command

运行参数数组形式的本机命令。

codex_exec_readonly

让 Codex 做一次只读检查。

codex_turn

启动一个持续工作的 Codex Turn。

文件读取和修改仍由 read_file、write_file、apply_patch 直接完成。

示例:创建测试 Step

create_workflow(
  project="Downloads/my-project",
  title="验证登录修复"
)
→ workflow_id
create_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_id
start_step(
  workflow_id=workflow_id,
  step_id=step_id,
  attempt=1
)
→ job_id
get_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 tools
apply_patchApply project patchB
Destructive

Apply an authorized Begin Patch block transactionally.

Inputs: patch (required), project (required). Returns: result

ask_codexAsk local CodexA
Read-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 jobB
Idempotent

Cancel a local Codex job; force only releases unconfirmed state.

Inputs: job_id (required), force. Returns: result

cancel_jobCancel command jobC
DestructiveIdempotent

Cancel a unified job; force only releases unconfirmed state.

Inputs: job_id (required), force. Returns: result

create_stepCreate workflow stepC
Idempotent

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 jobB
Read-onlyIdempotent

Get the status and result of a local Codex job.

Inputs: job_id (required). Returns: result

get_codex_turn_statusGet local Codex turn statusA
Read-onlyIdempotent

Get status, items, and final agent message for one Codex turn.

Inputs: turn_id (required), thread_id (required). Returns: result

get_jobGet command jobA
Read-onlyIdempotent

Get unified command, test, Codex, or Codex Turn job status.

Inputs: job_id (required). Returns: result

get_permissionsGet effective permissionsA
Read-onlyIdempotent

Return the effective root, hard boundaries, and tool-use policy.

Inputs: no named parameters. Returns: result

get_workflowGet workflowB
Read-onlyIdempotent

Get a durable Workflow with its Steps and Job attempts.

Inputs: workflow_id (required). Returns: result

git_commitCreate Git commitB
Destructive

Commit authorized paths without hooks, signing, filters, or pushing.

Inputs: paths (required), message (required), project (required). Returns: result

git_diffGet Git diffA
Read-onlyIdempotent

Return a bounded workspace or staged diff and its stat.

Inputs: project (required), path, scope. Returns: result

git_statusGet Git statusA
Read-onlyIdempotent

Return branch, HEAD, modified, staged, and untracked files.

Inputs: project (required). Returns: result

interrupt_codex_turnInterrupt local Codex turnC
DestructiveIdempotent

Interrupt an active local Codex turn.

Inputs: turn_id (required), thread_id (required). Returns: result

list_codex_threadsList local Codex threadsB
Read-onlyIdempotent

List local Codex app-server threads, optionally filtered by project.

Inputs: limit, cursor, project, archived, +1 more. Returns: result

list_filesList project filesA
Read-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 bridgeA
Read-onlyIdempotent

Return bridge process health without accessing project files.

Inputs: no named parameters. Returns: result

read_codex_threadRead local Codex threadB
Read-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 fileA
Read-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 threadA
Destructive

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 commandA
Destructive

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 testsA
Destructive

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 jobC
Read-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 turnA
Destructive

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 stepA
Idempotent

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 turnB
Destructive

Send additional instructions to an authorized active Codex turn.

Inputs: prompt (required), turn_id (required), thread_id (required). Returns: result

write_fileWrite project fileC
DestructiveIdempotent

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

    B3/5.0

    Scored across 28 tools

    Disambiguation2/5

    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.

    Naming Consistency3/5

    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.

    Tool Count2/5

    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.

    Completeness4/5

    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

    Related MCP Servers