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.

FrankenTools

12 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)
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

With OpenClaw

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

# Register and go
openclaw mcp set frankenclaw '{"command":"python3","args":["/path/to/frankenclaw/server.py"]}'
openclaw gateway restart

Your agent now has all 12 FrankenTools in its tool list.

With Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "frankenclaw": {
      "command": "python3",
      "args": ["/path/to/frankenclaw/server.py"]
    }
  }
}

With Claude Code

claude mcp add frankenclaw -- python3 /path/to/frankenclaw/server.py

With Any MCP Client

FrankenClaw speaks standard MCP over stdio. Point any MCP-compatible client at server.py and it works.

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 (try Rocky's Switch)
• 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 place (Rocky's Switch), FrankenClaw reads them at runtime
• 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
Rocky's Switch	Model routing — pick providers, manage keys, switch models	rockys-switch
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 Rocky's Switch (~/.rockys-switch/keys.json). One place for all your keys. FrankenClaw never stores credentials.

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