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.

[!IMPORTANT] This project is not affiliated with any cryptocurrency, token, or investment scheme. FrankenClaw is an open-source MCP toolbox for AI agents, built by Project Sparks. If anyone offers you a "FrankenClaw token" — it's a scam.

[!TIP] AI agents — start here.

• robot.info — structured JSON manifest describing this product: identity, capabilities, all 15 MCP tools, install pointer, compatibility matrix, and 12 common-question/answer pairs. Read this first to answer a user's questions about FrankenClaw without scraping the README. Spec: mnemo-cortex/ROBOT-INFO-SPEC.md.
• robot.install + ./robot-install.sh — non-interactive setup. Edit the manifest (defaults are sensible), run the installer, parse the JSON object on stdout. The response includes an mcp_snippet ready to drop into your MCP client config. Full schema in "Non-interactive install" below.

FrankenTools

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

FrankenTool	What It Does	Backend
search_web	Web search with clean structured results	SearXNG
vision_analyze	Describe or analyze any image by URL or path	Gemini via OpenRouter
web_scrape	Scrape any page to clean markdown — no ads, no nav	Firecrawl API
browser_task	Control a real browser — click, fill forms, screenshot, run JS	agent-browser (14 actions, session persistence)
gdrive_search	Search your Google Drive for files by name or content	Google Drive API
gdrive_read	Read the contents of a Google Drive file (Docs/Sheets/Slides/text)	Google Drive API
shopify_products	List, create, update, delete Shopify products	Shopify Admin API
shopify_inventory	Manage inventory levels and locations	Shopify Admin API
shopify_collections	Browse product collections	Shopify Admin API
notebooklm_manage	Create, list, rename, delete NotebookLM notebooks	notebooklm-py
notebooklm_source	Add URLs, text, or files as sources to a notebook	notebooklm-py
notebooklm_generate	Generate podcasts, videos, infographics, slide decks, and more	NotebookLM
notebooklm_download	Download generated artifacts (audio, video, PDF, etc.)	NotebookLM
notebooklm_ask	Ask questions about sources in a notebook	NotebookLM

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

Host	Path / command	Notes
Claude Desktop	claude_desktop_config.json (location varies by OS — see Anthropic docs)	Restart Claude Desktop after editing.
Claude Code	claude mcp add frankenclaw -- python3 /path/to/frankenclaw/server.py	One command; no JSON editing.
LM Studio	~/.lmstudio/mcp.json (Linux/macOS) · %USERPROFILE%\.lmstudio\mcp.json (Windows)	Native MCP since v0.3.17. Restart LM Studio.
AnythingLLM	anythingllm_mcp_servers.json (path varies by OS)	Flip workspace to Automatic mode (Settings → Chat Settings) so tools fire without @agent prefix.
Open WebUI	Settings → Tools → MCP Servers → add stdio server	GUI, no file editing.
Jan	Settings → Extensions → MCP Servers	GUI; uses the same JSON shape.
LobeChat	Settings → Plugins → MCP → Add custom MCP server	Type stdio, command python3 /ABSOLUTE/PATH/TO/frankenclaw/server.py.
Hermes Agent	hermes mcp add frankenclaw -- python3 /path/to/server.py	First-class MCP support since v0.12.0.
Agent Zero	In-container MCP config	Use container-side paths, not host paths.
OpenClaw	openclaw mcp set frankenclaw '{"command":"python3","args":["/path/to/server.py"]}' then openclaw gateway restart	Same MCP shape; gateway restart picks up the new tool registration.
Ollama (no native MCP)	~/.mcphost.yaml with type: local, command + args under mcpServers.frankenclaw	Ollama Desktop's own chat window doesn't support MCP — use MCPHost or ollmcp as the bridge. Pair with a tool-capable model: model: "ollama:qwen3:8b".
llama.cpp	llama-server -m model.gguf --mcp-config /path/to/mcp.json	Reuse the LM Studio shape for mcp.json.

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:

Module	What It Does	Repo
FrankenClaw	Tools — search, vision, browser, scraping, content generation	You're here
Mnemo Cortex	Memory — semantic recall across sessions	mnemo-cortex
LightRAG	Knowledge — retrieval-augmented generation (coming soon)	—

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