Local Agent Automation MCP

A local MCP server for SQLite-backed TODOs and scheduled coding-agent jobs. MCP clients connect over stdio. A separate worker process runs the durable schedule, so stopping an editor or MCP client does not stop scheduled jobs.

Requirements

• Bun 1.4.2 or newer. The project has been implemented and checked with Bun 1.4.2.

• Linux for the systemd user-service integration.

• An MCP-compatible editor/client.

• At least one supported agent CLI installed and authenticated for scheduled work.

automation-mcp is already published on npm by an unrelated project. This repository therefore uses the npm package name local-agent-automation-mcp and reserves automation-mcp as its CLI name. Confirm availability and update this package name before publishing. The GitHub repository is brili99/automation-mcp.

Related MCP server: Universal MCP Gateway

Install

On macOS/Linux, the installer checks OS and architecture, bootstraps Bun 1.4.2 into the current user's Bun directory when necessary, installs the npm package through Bun, and verifies the CLI:

curl -fsSL https://raw.githubusercontent.com/brili99/automation-mcp/main/install.sh | sh

On Windows PowerShell:

irm https://raw.githubusercontent.com/brili99/automation-mcp/main/install.ps1 | iex

The current PowerShell installer supports Windows x64 and ARM64. Bun's official installer may update the current user's PATH. Restart the terminal/editor if the new PATH is not visible. No Administrator or sudo privileges are required.

With Bun already installed, direct global installation is:

bun add --global local-agent-automation-mcp

Or use npm as the distribution client when Bun is already installed:

npm install --global local-agent-automation-mcp

The executable is automation-mcp. Bun is also required at runtime because the package uses bun:sqlite.

Configure

The first command creates ~/.config/automation-mcp/config.json if it does not exist. It creates the default database at ~/.local/share/automation-mcp/automation.sqlite. Set AUTOMATION_MCP_CONFIG to choose another config file; databasePath can be absolute or relative to the config file. Existing config and database data are not overwritten. Jobs are created paused and are enabled only after the selected CLI passes version and workspace-sandbox preflight; explicit enable requests repeat that check.

Example configuration:

{
	"workspaceRoots": ["/home/me/projects"],
	"memoryTokenBudget": 1200,
	"maxRunDurationMs": 3600000,
	"maxOutputBytes": 1048576,
	"runHistoryLimit": 500
}

Add only directories in which scheduled agents are allowed to work. Job workspaces must be canonical directories inside an approved root. Credentials are not stored by this application; use the agent's supported credential store or a documented environment variable. Prompts and adapter configuration reject credential-shaped content; agent output is redacted before it is written to run history. The database is plaintext and relies on user-only filesystem permissions, so back it up and protect it as local application data.

MCP Client

The project includes .vscode/mcp.json for local stdio testing. A client can also launch the installed executable directly:

{
	"servers": {
		"local-agent-automation": {
			"type": "stdio",
			"command": "automation-mcp",
			"args": ["mcp"]
		}
	}
}

The MCP process keeps stdout reserved for protocol messages and sends diagnostics to stderr. Long executions return a run ID; poll run_status or run_history rather than waiting for an agent call inside a tool request.

TODOs And Jobs

TODOs are separate from scheduled jobs. Tools todo_add, todo_list, todo_update, todo_complete, todo_cancel, and todo_delete manage independent TODO records. The worker never claims TODOs.

Use job_create with an explicit cronExpression and IANA timezone; both values are saved as entered and are required again when updating a schedule. The service validates that the expression and timezone are valid but never invents or rewrites either. Missed schedule occurrences older than the short polling window are skipped after downtime. Duplicate scheduled occurrences are prevented by a database uniqueness constraint. At most one run is active globally, and there is at most one pending or active occurrence per job.

Other job tools list/update jobs, enable or pause schedules, queue job_run_now, inspect/cancel executions, and read/update/clear persistent memory. Updating a job preserves its prior enabled/paused state after adapter preflight; paused jobs keep their saved cron and timezone. A run queued while a job is paused is not claimed until the job is enabled again.

Agent Adapters And Safety

• OpenCode runs opencode run --auto after verifying run --help. Its process gets a deny-by-default permission policy: read/search/edit within the working directory are allowed; shell, external directories, web access, and subagents are denied.

• Codex runs codex exec --sandbox workspace-write --ask-for-approval never after verifying the installed help advertises the required controls.

• Antigravity runs agy -p --sandbox only when its existing ~/.gemini/antigravity-cli/settings.json validates enableTerminalSandbox: true and toolPermission: "proceed-in-sandbox". The app does not modify this file. Set allowNonWorkspaceAccess to false or leave it unset.

• Generic profiles require an executable and argv array, never a shell command string. The argv must include --sandbox workspace-write and {prompt}; a non-interactive preflight invocation and required help markers must be explicitly configured and present in CLI help.

Agent processes use spawn with shell execution disabled, a separate workspace cwd, a restricted inherited environment, bounded runtime and combined output, and cancellation escalation. They must not commit, push, merge, or use unrestricted host access. A CLI that cannot verify its non-interactive workspace sandbox is reported unsupported and is not run. OpenCode, Codex, or Antigravity authentication stored only in a desktop keyring may be unavailable under a headless service; use that CLI's documented headless credential method without putting secrets in the SQLite database.

Persistent Job Memory

Each job has its own structured note (decisions, currentState, constraints, nextSteps) stored separately from run history. A real GPT BPE tokenizer enforces the configurable memoryTokenBudget (default 1,200 tokens). The bounded note is included as untrusted task context in later runs, including after a worker restart; it is never treated as system policy or authorization.

Agent output may include the structured memory-update envelope. Invalid JSON, secrets, or an uncompactable update leaves the previous note unchanged. Compaction removes the oldest detail from list categories rather than truncating a note arbitrarily. job_memory_get, job_memory_set, and job_memory_clear allow inspection, explicit edits, per-job token-budget changes, and reset. Memory has an independent lifecycle and is not deleted by run-history retention.

Dashboard

Start the read-only dashboard with:

automation-mcp ui

It binds only to 127.0.0.1 (default port 4177), reads the same configured database, and reports worker health, jobs/schedules/next runs, active executions, and recent outcomes. It exposes no job mutation endpoints. Use automation-mcp ui --port 4178 to choose another local port.

Linux Worker Service

Install the systemd user unit and manage it without an interactive shell:

automation-mcp service install
automation-mcp service start
automation-mcp service status
automation-mcp service logs
automation-mcp service stop

The installer resolves Bun and records explicit executable, PATH, and config paths in ~/.config/systemd/user/automation-worker.service. To run jobs after logout/reboot, enable lingering separately: loginctl enable-linger "$USER" (or run automation-mcp service enable-lingering for the instruction). The service runs as your account and shares its database with MCP and the dashboard.

Backup And Recovery

Stop the worker before making a cold copy of the SQLite database, or use SQLite's online backup API/tool while it is live. Include the database's -wal file if copying files directly while a process is open; do not treat the main database file alone as a live backup. Protect backups like the original plaintext data. On worker restart, abandoned active runs are marked interrupted rather than replayed. Schedule occurrence records are idempotent.

Development And Verification

bun install
bun run typecheck
bun run lint
bun test
bun run build

The typecheck uses the shared strict configuration for source and tests. The test suite uses temporary SQLite databases and fake processes; it makes no paid agent calls. bun run check runs all local quality gates.

Troubleshooting

• automation-mcp: command not found: add Bun's global executable directory to PATH; on macOS/Linux this is usually ~/.bun/bin, and on Windows it is under %USERPROFILE%\.bun\bin.

• No approved workspace roots: add an absolute path in workspaceRoots, then create or update the job with a directory inside it.

• Adapter preflight says unsupported: install/update the agent CLI and verify its documented non-interactive sandbox flags; do not remove safety flags to make it pass.

• Antigravity does not start unattended: authenticate using a documented headless method and set the sandbox keys above in its own settings file.

• Worker status is stale: run automation-mcp service status and automation-mcp service logs; user keyrings may not be available in a headless session.

• Database is locked: verify there is only one worker, keep the same configured database path for all processes, and allow the 5-second SQLite busy timeout to handle brief contention.

• automation-mcp npm package name: it belongs to another publisher; install this project by its distinct package name until a verified package name change is made.

SDK References

• Official MCP TypeScript SDK

• Official server tools guide

• MCP stdio serving guide

• Bun SQLite

• Cron parser

• Antigravity sandbox