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 1つ

• 対応する Tunnel Runtime Key 1つ

macOS ではまず基本ツールをインストールできます：

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

一言で AI に任せる

この文をローカル端末を操作できる AI に送ってください：

https://github.com/ezra-y/local-agent-mcp を私のコンピュータにインストールし、README に従って設定、起動、検証を完了してください。

手動インストールは：ChatGPT へのインストール。

ハイライト

28 のツール

直接の delete_file Tool は公開されていません。apply_patch もファイル全体の削除を拒否します。

git_commit はデフォルトでリポジトリの Hook とコミット署名を無効にします。clean / process Git Filter を検出するとコミットを拒否し、構造化 Commit が暗黙的にリポジトリプログラムを実行するのを防ぎます。git_diff は外部 Diff と textconv も無効にします。

権限リソース

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

高権限エントリ

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 の実行方法

5 つの概念

実行順序

create_workflow
→ create_step
→ start_step
→ get_job / get_workflow

create_step は現在 4 つの実行タイプをサポートしています：

ファイルの読み取りと変更は、引き続き 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)

実行 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 プロファイル、ソースディレクトリを自動的に削除しません。どのデータを保持する必要があるかを確認して決定してください。

ライセンス

MIT、LICENSE を参照してください。

⚠️ デフォルト設定では大きなローカル権限が開放されます：ChatGPT は現在のユーザーの Home 下のほとんどのプロジェクトを読み書きでき、テスト、コマンド、ローカル Agent を実行できます。信頼できるコンピュータ、アカウント、プロジェクトでのみ使用してください。