MCP Setup

Connect localpress to an MCP host (Claude Desktop, Cursor, Claude Code, VS Code) and let an AI agent drive your media library directly.

localpress mcp is a stdio Model Context Protocol server. It exposes 20 typed tools and 3 resources, all backed by the same engine the CLI uses. Same binary, new entrypoint — no daemon, no hosting, no separate config.

What you get

• Typed tool surface — schemas advertise exactly which args each tool accepts; no more "agent guessed wrong about a flag" failures.
• Structured results — JSON objects, not text-blobs-that-happen-to-be-JSON.
• First-class capability discovery — the localpress://capabilities resource is the same data localpress doctor returns.
• Zero new infra — runs as a child process of your MCP host, talks JSON-RPC over stdin/stdout.

Prerequisites

1. Install localpress: brew install gfargo/localpress/localpress (or see Getting Started).
2. Connect at least one WordPress site: localpress init.
3. Verify with localpress --version (must be 1.14.0 or later).

Configure your MCP host

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "localpress": {
      "command": "localpress",
      "args": ["mcp"]
    }
  }
}

Restart Claude Desktop. You should see localpress tools appear in the tools list.

Claude Code

Add via the CLI:

claude mcp add localpress -- localpress mcp

Or edit ~/.claude.json (or your project's .mcp.json):

{
  "mcpServers": {
    "localpress": {
      "command": "localpress",
      "args": ["mcp"]
    }
  }
}

Cursor

Edit ~/.cursor/mcp.json:

{
  "mcpServers": {
    "localpress": {
      "command": "localpress",
      "args": ["mcp"]
    }
  }
}

VS Code (Continue / GitHub Copilot)

Add to .vscode/mcp.json in your workspace, or to user settings depending on your MCP-aware extension. The structure mirrors the configs above.

Anything else

Any MCP host that supports stdio servers works. The invocation is always localpress mcp with no further arguments.

Verify it's working

After restarting your host, ask the agent:

"List my configured localpress sites."

The agent should call the sites_list tool and return the list. If it doesn't see the tools, check the host's MCP server logs (each host exposes them differently — Claude Desktop shows them in Settings → Developer → MCP logs).

What's available

Tools (33)

Resources (4)

How it works

Each tool dispatches by recursively spawning the localpress binary with --json --quiet. The server captures stdout, parses the JSON, and returns it to the host as a structured result.

This means:

• Every CLI feature appears in the MCP server with zero per-tool engine code.
• New CLI features auto-propagate.
• The CLI's stable --json contract (which the skill already depends on) is reused.

Hot paths can migrate to in-process dispatch later for lower latency and progress streaming, without changing the tool schemas.

Site selection

Every tool accepts an optional site argument. When omitted, the active site from config is used — same behavior as the CLI's --site flag.

// Agent call against the active site
{ "name": "list", "arguments": { "unoptimized": true } }

// Agent call against a specific site
{ "name": "list", "arguments": { "site": "production", "unoptimized": true } }

Parallelism

Bulk tools (optimize, convert, resize, remove_bg, caption, export, import) accept an optional concurrency field. Without it, the CLI defaults to CPU count − 1. Set it explicitly for large libraries:

{ "name": "caption", "arguments": { "missingAlt": true, "apply": true, "concurrency": 4 } }

Bulk captioning ~300 images at ~6-18s each drops from 30-90 minutes serially to ~8-23 minutes at concurrency=4.

Safe-by-default for bulk operations

Tools that accept unoptimized: true or all: true (optimize, convert, resize, caption, remove_bg) mirror the CLI's safe-by-default behavior: they dry-run unless apply: true is also passed. Explicit ids execute immediately.

// Dry-run preview
{ "name": "optimize", "arguments": { "unoptimized": true } }

// Actually execute
{ "name": "optimize", "arguments": { "unoptimized": true, "apply": true } }

Not exposed via MCP

The following CLI commands intentionally don't appear as MCP tools — they require TTY interaction and aren't meaningful in an agentic context. Use the CLI directly for these:

• init — interactive site wizard (use sites_add for non-interactive registration)
• edit — opens a desktop editor, watches for saves
• watch — long-running directory sync
• update — self-update the binary
• completions — emit shell completion scripts

Example agent workflows

Audit and fix in one session

"Audit my production site and optimize anything that's unoptimized."

The agent will:

1. Call doctor to verify the site is reachable.
2. Call audit to find issues.
3. Call optimize with unoptimized: true, apply: true to execute.
4. Call stats to confirm savings.

Bulk caption missing alt text

"Generate Spanish-language alt text for every image on my site that's missing it."

The agent will:

1. Call caption with missingAlt: true, language: "Spanish", apply: true.
2. Stream the results.

Compose with a WordPress MCP server

If you also have a WordPress MCP server connected (mcp-adapter, docdyhr/mcp-wordpress, etc.), the agent can mix tool calls:

1. Use the WP MCP to find a specific post's featured images.
2. Use localpress remove_bg to process them.
3. Use the WP MCP again to verify the updated _thumbnail_id.

See AI Agent Integration for more composition patterns.

Troubleshooting

Tools don't appear in the host

• Restart the host after editing the config.
• Run localpress mcp directly in a terminal — if it errors, you have a localpress install issue.
• Check the host's MCP logs (each host exposes them differently).

"No active site" errors

The MCP server reads the same config as the CLI. Run localpress sites to confirm a site is active, or pass site: "<name>" explicitly in tool calls.

Slow tool calls

Each tool spawn carries ~50-200ms of process-startup overhead. For interactive single-shot operations this is invisible; for bulk ops where the underlying CLI work takes seconds, it's negligible. Long-running ops (bulk optimize, caption) return the final JSON only — no streaming progress yet (tracked for v1.x).

"Capability unavailable" errors

Some operations (regenerate, full reference scans, replace-in-place) require WP-CLI over SSH. Configure SSH in localpress init for those, or use the REST-only fallback path. See WP-CLI / SSH Setup.

See also

• AI Agent Integration — the markdown skill for hosts without MCP support
• Commands Reference — full CLI command list
• Getting Started — install and first-site setup