FrankenClaw

Give your AI agent real tools — without losing control of cost or models.

FrankenClaw is a controlled execution layer for AI agents. It serves FrankenTools over standard MCP — search, vision, browser automation, web scraping, Shopify, and content generation — so any agent can use them. You pick the models. You control the keys. The tools just execute.

Drop a Python file in the tools/ folder. It auto-registers. No config. No wiring. That's it.

FrankenTools

14 tools. Each one is a single Python file. Use the whole box or just the tools you need.

Quick Start

FrankenClaw speaks standard MCP over stdio. Any MCP-capable host spawns server.py and gets all 14 FrankenTools in its tool list. The config shape is the same everywhere — only the location of the host's config file changes.

git clone https://github.com/GuyMannDude/frankenclaw.git
cd frankenclaw
pip install -r requirements.txt

The universal config block

Drop this into your MCP host's config file (location per host below):

{
  "mcpServers": {
    "frankenclaw": {
      "command": "python3",
      "args": ["/ABSOLUTE/PATH/TO/frankenclaw/server.py"]
    }
  }
}

Or skip the manual step and let ./robot-install.sh emit a ready-to-paste mcp_snippet block — it points at the venv's Python so the host doesn't accidentally launch FrankenClaw against system Python.

Where the config file lives, per host

Things to get right for every host

• Absolute paths only. Relative paths break silently — the host spawns FrankenClaw from the wrong cwd and Python throws ENOENT.

• Use a tool-capable model. Qwen3, Llama 3.2, Mistral, and Gemma 2 invoke tools correctly. Small models often narrate tool calls instead of making them — qwen3:8b verified working on AnythingLLM, llama3.1:8b known to fake calls.

• Coexists cleanly with Mnemo Cortex. Just add a second mcpServers entry. They don't conflict — your agent gets memory + hands in the same session.

Heads-up for Windows users: install and run FrankenClaw inside WSL2, not native Windows. agent-browser (the engine behind browser_task) ships native Linux/macOS binaries, and the SSH-stdio shortcut some hosts try to use is buffered to uselessness on Windows. The other 13 tools work native-Windows in theory; WSL2 is the verified path.

For host pass/fail, browser automation comparisons, and the rest of our field findings: projectsparks.ai/field-guide.

Non-interactive install (for LLM agents and CI)

Skip the manual steps — fill out a JSON manifest and run the robot installer.

# Defaults are sensible; only edit robot.install if you want different keys, vision model, etc.
./robot-install.sh

The script emits a single JSON object on stdout for the caller to parse; all human-readable progress goes to stderr.

{
  "ok": true,
  "steps": {
    "deps":       {"ok": true, "python": "3.12"},
    "venv":       {"ok": true, "path": "..."},
    "pip":        {"ok": true},
    "config":     {"ok": true, "config_path": "~/.frankenclaw/config.json", "keys_path": "~/.frankenclaw/keys.json"},
    "keys":       {"ok": true, "providers_written": ["openrouter"], "providers_missing": ["firecrawl"]},
    "smoke_test": {"ok": true, "loaded": [...], "failed": {}}
  },
  "mcp_snippet": {
    "command": "/path/to/.venv/bin/python",
    "args": ["/path/to/frankenclaw/server.py"]
  }
}

mcp_snippet is the value you drop into your MCP client config under mcpServers.frankenclaw. No path-juggling.

A tool module that fails to import is not a failure — FrankenClaw comes up with whatever tools have their deps satisfied. The smoke step reports failed per-module so you know what to install if you want the full set.

API keys are read from your install-time environment (OPENROUTER_API_KEY, FIRECRAWL_API_KEY, SEARXNG_API_KEY — names configurable in the manifest's provider_keys block) and copied to ~/.frankenclaw/keys.json with chmod 600. Missing keys leave empty placeholders so the file shape is obvious.

# Sandbox / dry-run — skips pip install and the smoke step
FRANKENCLAW_INSTALL_VENV_DIR=/tmp/test-venv \
FRANKENCLAW_INSTALL_DRY_RUN=1 \
./robot-install.sh

Add Your Own FrankenTools

FrankenClaw auto-discovers tools from the tools/ directory. To add one:

1. Create a Python file in tools/

2. Write an async function with a docstring

3. Restart FrankenClaw

That's it. No server.py edits. No registration. No config.

# tools/my_tool.py

async def my_cool_tool(query: str, limit: int = 10) -> str:
    """
    Does something cool.

    Args:
        query: What to look for.
        limit: Max results (default: 10).

    Returns:
        JSON with results.
    """
    # Your code here
    return '{"result": "done"}'

Functions starting with _ are ignored (use them for helpers). Every public async function becomes a FrankenTool.

Search Routing

FrankenClaw adds a web search tool (search_web) to your agent. If your agent already has a built-in web search (like OpenClaw's Brave search), you now have two web search tools competing for the same word "search."

If you also use Mnemo Cortex for agent memory, that's three search systems triggered by one word.

The model will default to whichever tool it pattern-matches first — usually the built-in one. Prompt-based routing instructions ("check memory first") are unreliable because tool selection happens before the model processes system prompt logic.

The fix: plain-language search commands.

Add these to your agent's system prompt or behavioral instructions:

• Msearch [query] — Memory search only (Mnemo Cortex). Does not touch web search.

• Fsearch [query] — FrankenClaw web search only. Does not touch memory.

• Wsearch [query] — Same as Fsearch. Web search.

• Recall [query] — Same as Msearch. Memory search.

• search [query] — Agent decides based on context (may default to built-in web search).

These are plain words, not slash commands. They work because they're unambiguous — no tool is named "Msearch" or "Fsearch," so the model can't reflexively grab the wrong one.

Msearch and Fsearch are non-negotiable overrides. When a user says Msearch, the agent searches memory. When they say Fsearch or Wsearch, it searches the web. No routing logic needed — the word itself IS the routing.

Architecture

FrankenClaw is a pure function. Request in, result out.

• No memory — your agent has that (try Mnemo Cortex)

• No model routing — your agent has that (use any OpenAI-compatible endpoint)

• No conversation context — your agent framework has that

• No agent brain — the agent IS the agent

The tool is an IO device, not intelligence. Each piece does one thing. Snap them together however you want.

Security

• Runs locally — FrankenClaw executes on your machine, not in the cloud

• No key duplication — API keys live in one keys.json file (FrankenClaw reads it at runtime, never copies)

• You control providers — pick which models handle which jobs

• No hidden API costs — route cheap models to grunt work, smart models to decisions, free models to filler

The Vision

FrankenClaw is part of a modular, open-source agent stack. Every piece connects via MCP. Mix and match:

No vendor lock-in. No monolith. Just MCP servers that do their job.

Configuration

API Keys are read from a flat JSON keys file. Default location is ~/.frankenclaw/keys.json. Override with FRANKENCLAW_KEYS_PATH to point at any file. For back-compat, if neither exists FrankenClaw falls back to the legacy ~/.rockys-switch/keys.json (with a stderr deprecation warning — move the file when convenient).

{
  "firecrawl": "fc-...",
  "openrouter": "sk-or-...",
  "shopify": {
    "store": "your-store.myshopify.com",
    "client_id": "...",
    "client_secret": "..."
  }
}

FrankenClaw never stores credentials — it reads the file at runtime.

Per-tool overrides via env vars:

• FRANKENCLAW_KEYS_PATH — point at any keys.json file

• FRANKENCLAW_SHOPIFY_KEY — pick which entry in keys.json holds Shopify creds (default: shopify)

• FRANKENCLAW_GDRIVE_TOKEN_PATH / FRANKENCLAW_GDRIVE_CLIENT_SECRET_PATH — Google Drive OAuth paths

Tool settings live at ~/.frankenclaw/config.json (auto-created on first run with sane defaults). Configurable options include vision model, browser engine, search result limits, and timeouts.

Requirements

• Python 3.12+

• agent-browser — npm install -g agent-browser (for browser_task)

• SearXNG instance (for search_web) — or swap in your own search

• Firecrawl API key (for web_scrape)

• NotebookLM auth via notebooklm login (for notebooklm tools)

pip install -r requirements.txt

Browser Automation

browser_task gives your agent a real, visible browser window. The agent clicks, fills forms, takes screenshots — you watch it happen in real time. Powered by agent-browser from Vercel Labs.

Key features:

• Persistent sessions — browser stays open between tool calls

• Visible by default — watch your agent browse (visible=True)

• Accessibility snapshots — agent reads the page structure, finds elements by ref

• 14 actions — open, snapshot, click, fill, type, press, screenshot, eval, scroll, back, forward, wait, close, upload

Built With

SPARC principles. AI designed for AI. From Project Sparks.

License

MIT