local-agent-tools

An experimental MCP server that lets an AI agent operate the machine it runs on: read and edit files, run commands, keep multi-stage Tasks with original receipts, browse project directories, delegate browser subtasks to a local Codex, and read built-in operating Skills.

Experimental and unmaintained. No releases, support or compatibility promises.

Install

Python 3.12 or newer on macOS or Linux, with Git. From a local checkout:

python3 -m venv .venv
.venv/bin/python -m pip install -r requirements.lock
.venv/bin/python -m pip install --no-deps --no-build-isolation .

Tasks are stored in SQLite and need SQLite 3.51.3 or newer, or a patched 3.50.7+ or 3.44.6+ release. Check the interpreter the server runs on with .venv/bin/python -c 'import sqlite3; print(sqlite3.sqlite_version)'; the python.org 3.12 and 3.13 installers ship older versions. The first create_task or save_task creates the Task database. With an older SQLite, Task writes fail with task_sqlite_unsupported, and once a Task database exists so do file writes, commands and worktree creation, which check it for Task reservations. Reads work with any SQLite.

Related MCP server: local-agent-mcp

Configure

.venv/bin/local-agent-tools init --workspace /absolute/path/to/project

This writes ~/.config/local-agent-tools/config.toml (mode 0600) and never overwrites it. By default access is read-only. Commands need --local-access full_access --enable-commands; file writes need --local-access full_access --enable-workspace-writes. Private state lives in ~/.local/state/local-agent-tools. --config and --state-dir go before the subcommand.

Use with an MCP client

The server speaks MCP over stdio; the client starts it. One server runs per state directory, and a second one on the same directory is refused, so give each client its own --state-dir under ~/.local/state/local-agent-tools/clients/, where scoped commands cannot reach it. Each state directory coordinates only itself: locks, resource leases, Tasks and receipts do not cover other clients, so give concurrent clients separate workspaces or worktrees.

{
  "mcpServers": {
    "local-agent-tools": {
      "command": "/absolute/path/to/.venv/bin/local-agent-tools",
      "args": ["--state-dir", "/Users/you/.local/state/local-agent-tools/clients/this-client", "serve"]
    }
  }
}

Security

The tools act as your user account, not inside a sandbox:

• Reads reach any directory your account can read, not only configured workspaces; only credential-named paths (such as .ssh, .env* and *.key) are refused.

• With Full Access, enabled commands and file writes apply to everything your account can change, not only configured workspaces.

• A call may carry an operation_scope, which confines that call's command under macOS Seatbelt and its file writes to the scoped Full roots; Linux refuses scoped commands. Typed file tools check scope by path spelling, so another spelling of the same place (such as /System/Volumes/Data/...) can pass them. The calling client chooses whether to send a scope, so it does not restrain an untrusted agent.

• File contents and command output go to the client and its model provider; redaction is best effort.

Enable commands and writes only for an agent you trust with your account.