frankenclaw

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

Non-interactive install (for LLM agents and CI)

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

```bash

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.

`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 ```

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

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.