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에 설치를 참고하세요.

주요 기능

28개 도구

직접적인 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

고권한 진입점

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 실행 방식

다섯 가지 개념

실행 순서

create_workflow
→ create_step
→ start_step
→ get_job / get_workflow

create_step은 현재 네 가지 실행 유형을 지원합니다:

파일 읽기 및 수정은 여전히 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=2와 같은 새 attempt를 사용하세요.

병렬 규칙

同一个 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는 이전 import 및 이전 시작 방식의 호환 별칭으로 유지됩니다.

제거 및 로컬 데이터

제거 프로그램은 SQLite, Artifact, Tunnel profile 또는 소스 디렉터리를 자동으로 삭제하지 않습니다. 먼저 확인하고 어떤 데이터를 유지할지 결정하세요.

License

MIT, LICENSE 참조.

⚠️ 기본 구성은 상당히 넓은 로컬 권한을 엽니다. ChatGPT가 현재 사용자 Home의 대부분 프로젝트를 읽고 쓸 수 있으며, 테스트, 명령, 로컬 Agent를 실행할 수 있습니다. 신뢰하는 컴퓨터, 계정, 프로젝트에서만 사용하세요.