Skip to main content
Glama
deenesjakoruzh
ezra-y

local-agent-mcp

by ezra-y
OverviewSchemaRelated ServersScoreDiscussions
Python
Local

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；请只在你信任的电脑、账号和项目中使用。

Install Server
A
license - permissive license
B
quality
C
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
–Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Tools

View all tools

Related MCP Servers

  • localterminal-lite

    wyj-IIRtyj
    A
    license
    Not graded
    quality
    A
    maintenance
    Bridges ChatGPT with local computer for controlled file and project management, featuring session-based collaboration and diff tracking.
    4
    Apache 2.0

View all related MCP servers

Related MCP Connectors

  • local-mcp

    Let ChatGPT, Claude & Cursor use your Mac: email, calendar, iMessage, Teams, files. Local, free.

  • Hexis

    Git-backed platform for skills, tools, and context for AI agents

  • AgentDrive

    Cross-agent artifact workspace with provenance across Claude Code, Codex, Cursor, LangGraph.

View all MCP Connectors

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/ezra-y/local-agent-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server