ai-workers-mcp

MCP server that routes commodity NLP tasks (summarize, translate, rewrite, proofread, …) to free-tier LLMs, saving Claude tokens for work that actually needs them. Multi-provider, multi-account, with round-robin, automatic fallback, in-memory caching, and daily usage tracking.

Tools

All exposed as ai_* MCP tools and as /<verb>-ai slash commands.

NLP tools

Observability & config tools

Every response carries a provider/model banner: 🔷 **gemini · gemini-2.5-flash** ────.

Large-text support

All text tools auto-chunk inputs over 50 000 characters and merge results (map-reduce for summarize/qa, chunk-outline-merge for outline, majority-vote or truncate for classify, per-field merge for extract, concatenation for others). No manual splitting needed.

Related MCP server: local-llm-delegation-mcp

Slash commands

Each NLP tool has three slash-command variants (48 total, in .claude/commands/):

• /<verb>-ai — result shown in chat (with banner)

• /<verb>-ai-replace — replaces the editor selection

• /<verb>-ai-append — inserts the result after the selection

NLP verbs: generate, summarize, translate, rewrite, proofread, list, outline, classify, extract, ask, compare, draft, keywords, sentiment, title.

Observability verbs (chat only): usage, check-limits, configure.

Input priority: argument › editor selection › clipboard › interactive prompt.

Multi-value arguments use / as separator:

• /translate-ai en/es/nl → translates into English, Spanish, and Dutch in one call

• /rewrite-ai formal/concise → returns both rewrites in one response

Overflow handling

For very long inputs (> 50 000 chars), slash commands for classify ask which strategy to use:

1. truncate — classify the first 50 000 characters only

2. vote — classify each chunk independently, return the majority label

3. skip — cancel

/ask-ai and /outline-ai handle overflow automatically (map-reduce and chunk-outline-merge respectively).

Setup

1. Configure providers & keys

Copy the example and add your key(s):

cp ai-workers.example.json ~/.config/ai-workers.json
chmod 600 ~/.config/ai-workers.json
# edit ~/.config/ai-workers.json

Get a free Gemini key at aistudio.google.com. Use gemini-2.5-flash (free tier). Add more keys to multiply your free quota, or add Groq/Mistral/OpenRouter blocks to order for cross-provider fallback.

2. Install (cross-platform)

macOS / Linux / inside WSL:

./setup.sh

Windows (Claude Code on Windows, server in WSL):

.\setup.ps1

The installer builds the server, deploys the slash commands to your user scope, and registers the MCP server in your Claude Code config.

3. Reload Claude Code

Run /mcp to confirm ai-workers is connected.

Portability

The core (src/**) is plain Node — runs identically on macOS, Linux, WSL, and Windows. The only platform-specific glue is the per-machine MCP registration, handled by the two setup scripts. Secrets live solely in ~/.config/ai-workers.json (resolved via homedir()), never in the Claude config.

Privacy

A rules-based filter runs before any text leaves your machine. It blocks file paths, code patterns, and credential patterns (sends nothing, returns an error), and warns on emails/phone numbers (prepends a notice, still sends). Keep inputs plain prose.

Configuration reference

~/.config/ai-workers.json — read once at server start (use /configure-ai reload or ai_reload_config to apply changes live):

{
  "order": ["gemini", "groq", "mistral"],
  "providers": {
    "gemini": {
      "baseURL": "https://generativelanguage.googleapis.com/v1beta/openai/",
      "model": "gemini-2.5-flash",
      "keys": ["KEY_1", "KEY_2"],
      "dailyLimit": 1000
    },
    "groq": {
      "baseURL": "https://api.groq.com/openai/v1/",
      "model": "llama-3.3-70b-versatile",
      "keys": ["YOUR_GROQ_KEY"],
      "dailyLimit": 1000
    },
    "mistral": {
      "baseURL": "https://api.mistral.ai/v1/",
      "model": "mistral-small-latest",
      "keys": ["YOUR_MISTRAL_KEY"],
      "dailyLimit": 1000
    }
  }
}

Round-robin rotates across a provider's keys; 429 triggers escalating cooldown (60s → 1h), 401/403 a long cooldown, then falls through to the next provider in order. Falls back to the GEMINI_API_KEY env var if no config file exists.

Caching

Text and URL results are cached in memory per tool:

Override at runtime: /configure-ai ttl <tool> <ms> or call ai_set_ttl directly.

Usage tracking

Every LLM call is recorded to ~/.config/ai-workers-usage.json (per-key ok/error counts, reset at Pacific midnight). Run /usage-ai or call ai_usage to see today's table.

Rebuilding after changes

npm run build

Then reload Claude Code (or use ai_reload_config if only the JSON config changed).