Local Worker MCP

Client-agnostic local MCP. Frontier plans, delegates, and reviews. Local does the heavy, mechanical, and verifiable work.

The goal is to reduce token consumption from paid AIs without dumping raw content into their context.

Codex / Claude / Gemini / Grok
              │
              ▼
       Local Worker MCP
              │
       ┌──────┴───────────────┐
       ▼                      ▼
 Gemma 4 12B QAT          arquivos / PDF
 via Ollama               extração + evidências
       │
       ▼
 resultado compacto e verificável
       │
       ▼
 Frontier revisa

This does not replace the main AI and is not a model router. It is real task delegation.

LOCAL DISPONÍVEL?          NÃO
      │                     │
      ▼                     ▼
   DELEGA                NÃO INSISTE
      │                     │
      ▼                     ▼
   COMPRIME            FRONTIER ASSUME
      │
      ▼
 FRONTIER REVISA

Gemma is an optimization. It must never become a single point of failure.

Principle

Delegate when the task is mechanical, repetitive, verifiable, or context-intensive: PDF, logs, CSV, code, extraction, classification, summarization.

Keep on the frontier: architectural decisions, security, critical changes, subjective judgment, ambiguous requirements.

If the local worker is offline, the frontier continues. The MCP returns unavailable quickly and recommends a fallback. The client can log:

Worker local indisponível; executei diretamente.

Does not require user intervention.

Related MCP server: ollama-handoff

Requirements

• Python 3.10+

• Ollama on the same PC or another on the LAN

• A local model (recommended: Gemma 4 12B QAT)

Installation

git clone https://github.com/CaioAllgayer/Local-Worker-MCP.git
cd Local-Worker-MCP
python -m pip install -e ".[dev]"
copy .env.example .env

Ollama + Gemma

1. Install and start Ollama.

2. Download the model. The name is not hardcoded — use the actual name from your ollama list:

ollama list
ollama pull <nome-real-do-gemma>

3. If LOCAL_LLM_MODEL is empty, the worker tries to detect a model whose name contains gemma. Otherwise, it uses the first listed model.

4. Test the endpoint:

curl http://127.0.0.1:11434/api/tags
local-worker status

5. Start the MCP:

local-worker-mcp

Same PC

LOCAL_LLM_PROVIDER=ollama
LOCAL_LLM_BASE_URL=http://127.0.0.1:11434
LOCAL_LLM_MODEL=

local vs lan is detected by hostname. 127.0.0.1, localhost, and ::1 are local.

Laptop using the desktop

The worker does not assume localhost. The backend can be on another PC on the LAN.

On the laptop:

LOCAL_LLM_PROVIDER=ollama
LOCAL_LLM_BASE_URL=http://192.168.x.x:11434

Replace 192.168.x.x with the current IP of the desktop (ipconfig on Windows, ip a on Linux). There is no fixed IP in the project.

The behavior is the same: fail-fast, circuit breaker, cache, compression.

On the desktop, Ollama must accept connections from the LAN (OLLAMA_HOST=0.0.0.0 environment variable and firewall allowing port 11434).

OpenAI-compatible

LM Studio, llama.cpp server, vLLM, and similar:

LOCAL_LLM_PROVIDER=openai_compatible
LOCAL_LLM_BASE_URL=http://127.0.0.1:1234/v1
LOCAL_LLM_MODEL=...
LOCAL_LLM_API_KEY=

Fail-fast and circuit breaker

Defaults:

LOCAL_LLM_CONNECT_TIMEOUT_SECONDS=2
LOCAL_LLM_REQUEST_TIMEOUT_SECONDS=45
LOCAL_LLM_MAX_RETRIES=0
LOCAL_LLM_CIRCUIT_BREAKER_FAILURES=2
LOCAL_LLM_CIRCUIT_BREAKER_COOLDOWN_SECONDS=60

Connection refused does not retry. After N failures the circuit opens and subsequent calls return unavailable immediately. After the cooldown, one attempt is allowed.

{
  "status": "unavailable",
  "fallback_recommended": true,
  "reason": "Local LLM endpoint unreachable"
}

MCP Tools

The raw file content does not need to enter the paid AI's context. The worker reads, compresses, and returns verifiable evidence (page, line, snippet).

Security

Default: SECURITY_MODE=READ_ONLY, ENABLE_SHELL=false.

SECURITY_MODE=READ_ONLY
ALLOWED_PATHS=C:\Projects,D:\Research
ENABLE_SHELL=false

• READ_ONLY — read-only on authorized paths; write and shell blocked

• WORKSPACE_WRITE — read/write on authorized paths; shell only if ENABLE_SHELL=true

• FULL_LOCAL — more permissive; still blocks destructive commands

Path traversal is blocked. rm, del, format, etc. are refused.

Cache and logs

Persistent cache in ~/.local-worker-mcp/cache, self-cleaning:

CACHE_TTL_DAYS=30
CACHE_MAX_SIZE_GB=10
CACHE_CLEANUP_THRESHOLD_PERCENT=90
CACHE_TARGET_USAGE_PERCENT=80
CACHE_CLEANUP_INTERVAL_HOURS=6

Entries are disposable by default. persistent=true preserves important artifacts.

Logs rotate and expire:

LOG_RETENTION_DAYS=14
LOG_MAX_SIZE_MB=250

The log does not store the full file content.

Benchmark

local-worker benchmark arquivo.pdf

Output:

Arquivo: arquivo.pdf
Worker: gemma4:12b-qat
Backend: ollama
Endpoint: LAN/local
Tamanho: ...
Tokens originais estimados: ...
Tokens processados localmente: ...
Resultado para frontier: ...
Compressão: ...
Tempo: ...
Cache: HIT/MISS

Codex

~/.codex/config.toml or the client's JSON:

{
  "mcpServers": {
    "local-worker": {
      "command": "local-worker-mcp",
      "env": {
        "LOCAL_LLM_PROVIDER": "ollama",
        "LOCAL_LLM_BASE_URL": "http://127.0.0.1:11434",
        "ALLOWED_PATHS": "C:\\Projects"
      }
    }
  }
}

See examples/codex.json.

Claude Code

claude mcp add local-worker --scope user -- local-worker-mcp

Or paste examples/claude_code.json into ~/.claude.json.

In the project's CLAUDE.md / AGENTS.md, teach the policy:

Mechanical tasks and reading large files go to delegate_pdf / delegate_file / delegate_task. If local_status or the tool returns unavailable, execute directly and move on.

Other MCP clients

Any stdio client works. Generic example in examples/generic.json:

{
  "mcpServers": {
    "local-worker": {
      "command": "local-worker-mcp",
      "env": {
        "LOCAL_LLM_PROVIDER": "ollama",
        "LOCAL_LLM_BASE_URL": "http://127.0.0.1:11434"
      }
    }
  }
}

Examples

• examples/pdf.md — long paper / PDF

• examples/code.md — initial repository reading

• examples/logs.md — error extraction

Tests

python -m pip install -e ".[dev]"
pytest
ruff check src tests

The suite does not depend on real Ollama/Gemma. Everything is mocked.

What is not included in this MVP

Windows GUI automation, Playwright, complex multi-agent, vector RAG, dashboard, Kubernetes, ML router.

The architecture leaves room for delegate_repo, delegate_git, delegate_browser, etc. in the next phase.

License

MIT.