Getting started with Katman

Before you start

• Node.js 20 or newer. Check with node --version.
• An AI coding tool that can run MCP servers: Claude Code, Cursor, VS Code with Copilot, Windsurf (now Devin Desktop), Codex CLI, Gemini CLI, Claude Desktop, Zed or Cline.
• Your site’s code on your computer. Katman reads the project folder your agent works in.
• A Katman key (KATMAN_KEY, starting km_live_). Every tool except katman_account needs it. It comes with Audit Week ($3, paid once, for 7 days) or Katman Pro: buy one, then create the key in your account at katman.pro/app → MCP. The steps are below.
• Optional: an OpenRouter API key, with some credit, for automated visibility runs. Create one at openrouter.ai/keys. You pay OpenRouter directly; it’s separate from what you pay for Audit Week or Pro.

Every client starts the same server, npx -y katman-mcp. Only the place you put that command and the keys differs. Keep keys in your user-level config or your environment, not in a file you commit.

Install

Claude Code

Run this in a terminal:

claude mcp add katman --scope user -e KATMAN_KEY=km_live_... -e OPENROUTER_API_KEY=sk-or-... -- npx -y katman-mcp

KATMAN_KEY is required. Leave out -e OPENROUTER_API_KEY=... until you want automated visibility runs. Options go after the name and before --. --scope user makes Katman available in every project. --scope project writes a .mcp.json your team can share; in that file, write ${KATMAN_KEY} and ${OPENROUTER_API_KEY} instead of the keys themselves (Claude Code docs). Already added without a key? Run claude mcp remove katman first.

Cursor

Put this in ~/.cursor/mcp.json (your user file, so the key never lands in a repository), or use the install button on the Katman page:

{
  "mcpServers": {
    "katman": {
      "command": "npx",
      "args": ["-y", "katman-mcp"],
      "env": {
        "KATMAN_KEY": "km_live_...",
        "OPENROUTER_API_KEY": "${env:OPENROUTER_API_KEY}"
      }
    }
  }
}

VS Code (Copilot agent mode)

Add this to .vscode/mcp.json. VS Code asks for the keys once and keeps them out of the file (VS Code docs):

{
  "inputs": [
    { "type": "promptString", "id": "katman-key", "description": "Katman key from katman.pro/app (required)", "password": true },
    { "type": "promptString", "id": "openrouter-key", "description": "OpenRouter API key (optional, only for visibility runs)", "password": true }
  ],
  "servers": {
    "katman": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "katman-mcp"],
      "env": { "KATMAN_KEY": "${input:katman-key}", "OPENROUTER_API_KEY": "${input:openrouter-key}" }
    }
  }
}

Windsurf (Devin Desktop)

Use the same mcpServers block as Cursor, keys included, in ~/.config/devin/mcp_config.json (on Windows, %APPDATA%\devin\mcp_config.json). Older Windsurf builds read ~/.codeium/windsurf/mcp_config.json. Refresh the MCP list afterwards.

Codex CLI

codex mcp add katman --env KATMAN_KEY=km_live_... --env OPENROUTER_API_KEY=sk-or-... -- npx -y katman-mcp

Or add a table to ~/.codex/config.toml. env_vars passes the keys from your shell, so they never sit in the file:

[mcp_servers.katman]
command = "npx"
args = ["-y", "katman-mcp"]
env_vars = ["KATMAN_KEY", "OPENROUTER_API_KEY"]
startup_timeout_sec = 30

Gemini CLI

gemini mcp add -s user -e KATMAN_KEY=km_live_... -e OPENROUTER_API_KEY=sk-or-... katman npx -- -y katman-mcp

In ~/.gemini/settings.json, use "env": { "KATMAN_KEY": "$KATMAN_KEY", "OPENROUTER_API_KEY": "$OPENROUTER_API_KEY" } inside mcpServers. Gemini CLI doesn’t pass variables with KEY or TOKEN in their names from your shell, so the keys must be listed under env.

Claude Desktop, Zed, Cline

Use the same command, arguments and env keys, KATMAN_KEY included. Claude Desktop has no project folder, so add "KATMAN_PROJECT_ROOT": "/absolute/path/to/your/project" to the env block and restart the app completely.

Lovable, Bolt, v0 and Replit

Katman runs on your computer, so it needs a local copy of the code. Sync the project to GitHub, clone it, and open it in one of the tools above. The live-site audit works on your public URL either way.

Add your Katman key

1. Buy Audit Week or Katman Pro: sign in at katman.pro/app and open Billing, or start from the pricing page.
   • Audit Week: $3, paid once, for 7 days from payment. It doesn’t renew, and each account can buy it once. It unlocks the audit and recommendation tools: it finds what’s wrong and tells you what to do.
   • Katman Pro: $29/month at the founding price for the first 100 customers (later $49/month), or $290/year. It unlocks every tool, including the ones that build pages and write files.
2. Open MCP and create a key. The full key is shown once; copy it then.
3. Put it in your client’s env block as KATMAN_KEY, as shown above, and restart the MCP server.
4. Ask your agent to run katman_account, the one tool that needs no key. It shows your plan (Audit Week with the days left, or Pro) and the features the key unlocks.

Without a valid key, the tools don’t run: they tell your agent how to get Audit Week or Pro and how to add the key. With an Audit Week key, the Pro-only tools explain that they need Pro; which tool needs which plan is on Tools. Katman checks your plan with katman.pro at most once a day, sending only the key and the MCP version; details are on Permissions.

Add your OpenRouter key (optional)

1. Create a key at openrouter.ai/keys and add a little credit.
2. Put it in your client’s env block as shown above, or export OPENROUTER_API_KEY (or KATMAN_OPENROUTER_API_KEY) in the environment your client starts from.
3. Restart the MCP server.

Katman reads both keys from the environment only, never writes them to disk and never prints them. Don’t paste a literal key into a file you commit. What a run costs is on Visibility runs.

Your first session

Open your site’s project and tell your agent:

Use Katman to make this site recommendable by ChatGPT.

The agent calls katman_start first. It reads .katman/, shows where you are in the four steps (research, plan, build, verify) and returns the next tool call. A typical first session, with example output:

you     Use Katman to make this site recommendable by ChatGPT
agent   → katman_start { "site_url": "https://your-site.com" }
katman  Step 1 of 4, Research: not started.
        Next: katman_research { "mode": "template" }
agent   → katman_scan_code {}
katman  Framework, rendering (server or browser), public routes, robots/sitemap/llms.txt.
agent   → katman_research { "mode": "template" }
katman  .katman/research.md created. Still to fill in: your one sentence,
        10–12 customer situations, competitors with source and date…
agent   (asks you for the missing items, then) → katman_audit_site { "url": "https://your-site.com" }
katman  Gate results: read / quote / fit, with the prompt that fixes each issue.
agent   → katman_plan {}
katman  plan.md: tasks in the book's order, each with its acceptance criterion.

Every tool in this session works with Audit Week or Pro. The build step that comes next, with the P0–P14 prompts, page briefs and generated files, needs Pro.

Katman never invents your one sentence, customers or competitor facts; it asks you and marks the gaps for you to fill in. Before any paid visibility run, the agent shows you a cost estimate and waits for your yes.

What appears in .katman/

The folder never contains secrets, so it’s safe to commit. Katman also keeps ~/.katman/license.json outside your project: the last plan check, stored under a hash of the key.

Slash commands and the command line

Katman also offers four MCP prompts, which many clients show as slash commands: katman-start, katman-audit (report only, no code changes), katman-situation-page and katman-measure. In Claude Code they appear as /mcp__katman__katman-start and so on.

The same package runs from a terminal:

npx -y katman-mcp scan .                          # codebase scan
npx -y katman-mcp audit https://your-site.com     # live audit
npx -y katman-mcp check --root .                  # visibility run (asks before spending)
npx -y katman-mcp report --root .                 # report.md

The command line follows the same tiers as the tools: scan, audit, keywords, plan, report and check need Audit Week or Pro, indexnow needs Pro, and account needs no key. Commands read KATMAN_KEY from the environment (in GitHub Actions, a repository secret). Without a key that covers the command (for example no key, an ended Audit Week, or indexnow on an Audit Week key), a command prints a short explanation and exits with code 4.

Next steps

• Every tool, its inputs and what it writes: Tools.
• What Katman reads, writes and sends: Permissions.
• Questions, models, costs and why one run is a small sample: Visibility runs.
• If the server doesn’t show up or a tool fails: Troubleshooting.