Local Agent MCP

English · Permissions · Architecture

Let ChatGPT Pro work directly on your local computer

You assign tasks in ChatGPT, and it can call local MCP tools: read projects, modify files, run tests, check Git Diff, create Commits.

Complex tasks can be handed off to local Codex. ChatGPT continues to handle breaking down steps, checking progress, adding requirements, and final review.

ChatGPT Pro
→ Local Agent MCP
→ 本地文件 / 测试 / Git / Codex

No need to repeatedly copy code, and no need to route every task through Codex.

This is an unofficial community project. It is not an OpenAI product and does not represent OpenAI.

Related MCP server: chatgpt-codex-tools-mcp

Quick Start

Prerequisites

Prepare the following:

• macOS or Linux

• Python 3.11 or later

• Git

• uv

• OpenAI official tunnel-client

• A ChatGPT environment that supports custom MCP Apps

• A Tunnel ID

• A corresponding Tunnel Runtime Key

On macOS, you can install the basic tools first:

brew install uv tmux
brew install openai/tools/tunnel-client

One sentence to hand it to AI

Send this sentence to an AI that can operate a local terminal:

Install https://github.com/ezra-y/local-agent-mcp on my computer, and follow the README to complete configuration, startup, and verification.

Manual installation: see Install to ChatGPT.

Highlights

28 Tools

A direct delete_file Tool is not exposed. apply_patch also refuses to delete entire files.

git_commit disables repository Hooks and commit signing by default. When a clean / process Git Filter is detected, it refuses to commit to avoid structured Commits implicitly running repository programs. git_diff also disables external Diff and textconv.

Permissions Resource

In addition to the get_permissions Tool, the service also provides:

local-agent://permissions

The content includes:

当前允许访问哪里
哪些目录和文件被禁止
读写是否开启
有没有直接删除工具
高权限入口有哪些

get_permissions will continue to be kept for clients that do not yet display MCP Resources.

Permissions and Privilege Reduction

Default Scope

Structured file and Git tools can access the current user's Home by default:

$HOME

This usually includes Desktop, Downloads, Documents, and other projects in personal directories.

Things Forbidden by Code

Structured file tools will refuse:

.ssh
.aws
.azure
.codex
.docker
.gnupg
.kube
.Trash
Library
.env 和 .env.*
常见凭据文件
.pem / .key / .p12 / .pfx 私钥文件
符号链接路径

Additionally:

• There is no direct file deletion Tool.

• apply_patch cannot delete entire files.

• There is no Git Push Tool.

• git_commit only commits explicitly listed paths.

Narrowing the Structured Scope

Set before startup:

export LOCAL_AGENT_MCP_ROOT="$HOME/Projects"

The old config name CODEX_MCP_ROOT remains compatible.

After that, these tools can only access $HOME/Projects:

list_files
read_file
write_file
apply_patch
git_status
git_diff
git_commit

Foreground startup example:

export LOCAL_AGENT_MCP_ROOT="$HOME/Projects"
./scripts/run_tunnel.sh

High-Permission Entry Points

LOCAL_AGENT_MCP_ROOT is the hard boundary for structured file and Git tools, not a system sandbox for the entire process.

When repository Hooks, Git LFS, or other Filters are needed, commit manually, or use the high-permission run_command after explicitly checking the repository configuration.

v0.5.1 does not yet have per-Tool hide or disable configuration. For stronger isolation, use a separate system user, virtual machine, container, or maintain a version with trimmed Tools.

Full details: docs/permissions.md.

Install to ChatGPT

1. Download and test

git clone https://github.com/ezra-y/local-agent-mcp.git
cd local-agent-mcp
uv sync --locked --all-groups
uv run pytest -q

Local Codex lookup order:

1. The path specified by CODEX_BIN.

2. codex in PATH.

3. The Codex built into the macOS ChatGPT App.

2. Save the Runtime Key

macOS:

./scripts/save_tunnel_key.sh

Linux:

export CONTROL_PLANE_API_KEY="<你的 Runtime Key>"

3. Generate Tunnel configuration

export CONTROL_PLANE_TUNNEL_ID="tunnel_<32位小写十六进制>"
./scripts/configure_tunnel.sh

Local configuration is saved at:

.runtime/profiles/

4. Start the Tunnel

Foreground:

./scripts/run_tunnel.sh

Background:

tmux new-session -d \
  -s local-agent-mcp-tunnel \
  -c "$PWD" \
  ./scripts/run_tunnel.sh

Wait for the service to be ready:

for i in {1..30}; do
  curl -fsS http://127.0.0.1:8741/readyz && break
  sleep 1
done

On success it returns:

ready

Local status page:

http://127.0.0.1:8741/ui

5. Connect in ChatGPT

1. Open Settings → Apps.

2. Enable Developer Mode.

3. Create or connect the corresponding custom MCP App.

4. After the Tunnel starts, click Refresh / Scan tools.

5. Start a new chat and select @Local Agent.

6. Verify

Send in a new chat:

@Local Agent

调用 get_permissions。
报告当前工具总数、版本和 allowed_root。

Expected result for v0.5.1:

工具总数：28
版本：0.5.1
allowed_root：你的 Home，或你设置的 LOCAL_AGENT_MCP_ROOT

If the client supports Resources, try reading:

local-agent://permissions

Run Local stdio MCP Only

When not using the ChatGPT Tunnel:

./scripts/run_mcp.sh

You can also install it as a global command:

uv tool install .
local-agent-mcp

The old command local-codex-mcp still works.

Daily Use

The project parameter in tools is usually a path relative to $HOME:

Documents/Codex/local-agent-mcp
Downloads/my-project
Desktop/example-project

Absolute paths inside Home are also supported. project="." represents the entire structured root directory; with default settings, that is the entire Home.

A Common Task

@Local Agent

在 Downloads/my-project 修复登录失败问题。
检查相关代码和 Git 状态，完成修改、测试、Diff 和 Commit。

Common flow:

get_permissions
→ git_status / list_files / read_file
→ write_file / apply_patch
→ run_tests
→ git_diff
→ git_commit

For complex tasks, you can add an explicit Workflow or local Codex.

How Workflows Run

Five Concepts

Execution Order

create_workflow
→ create_step
→ start_step
→ get_job / get_workflow

create_step currently supports four execution types:

File reading and modification are still done directly by read_file, write_file, and apply_patch.

Example: Creating a Test 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)

The execution identity is:

workflow_id + step_id + attempt

Starting again with the same number returns the original Job and does not execute again. For an explicit rerun, use a new attempt, e.g. attempt=2.

Parallel Rules

同一个 Codex Thread：同一时间一个活动 Turn
同一个 Worktree：同一时间一个写入者
同一个仓库：不同 Worktree 可以并行

Use steer_codex_turn to add requirements to an active Turn, and interrupt_codex_turn to stop it.

Local State and Logs

When running from source:

.runtime/state.sqlite3
.runtime/artifacts/<job_id>/

The installed command uses by default:

$HOME/.local/state/local-agent-mcp/state.sqlite3

Custom location:

export LOCAL_AGENT_MCP_STATE_PATH="/自定义位置/state.sqlite3"

The old config name CODEX_WORKFLOW_STATE_PATH remains compatible. Existing old state databases will continue to be read.

Long logs are stored in Artifact files. SQLite saves the path, size, and SHA-256.

Artifacts are not deleted automatically. When the total recorded amount exceeds 1 GiB, ping returns a warning.

Updates

git pull
uv sync --locked --all-groups
uv run pytest -q

Then restart the Tunnel and click Refresh / Scan tools in ChatGPT.

Project Structure

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 启动脚本

Test files are kept in the repository. They are used to verify permission boundaries, cross-platform operation, packaging, and compatibility; the installed wheel only contains runtime code.

Development Checks

uv run pytest -q
uv run python scripts/check_public_release.py
zsh -n scripts/*.sh
uv build

The main MCP entry point is src/local_agent_mcp/server.py. src/codex_bridge.py is kept as a compatibility alias for old imports and old startup methods.

Uninstall and Local Data

The uninstaller does not automatically delete SQLite, Artifacts, Tunnel profiles, or the source directory. Please check first and decide which data to keep.

License

MIT, see LICENSE.

⚠️ The default configuration opens fairly broad local permissions: ChatGPT can read and write most projects under the current user's Home, and can run tests, commands, and local Agents; only use this on computers, accounts, and projects you trust.