---
title: "Install Katman in Cursor, Claude Code or VS Code"
description: "Install Katman MCP in Cursor, Claude Code, VS Code, Windsurf, Codex or Gemini CLI, add your Katman key and optional OpenRouter key, and run your first session."
url: https://katman.pro/docs/getting-started
lang: en
updated: 2026-09-30
---

Docs Updated 30 Sep 2026

# Getting started with Katman

> Katman is a local MCP server that you add to your AI coding tool with one command or one JSON block; it needs Node.js 20 or newer. Every tool except katman_account needs KATMAN_KEY: buy Audit Week ($3 once, for 7 days) or Katman Pro, then create the key in your account at katman.pro/app → MCP. Automated visibility runs also need your own OpenRouter key. Then open your site’s project and tell your agent: “Use Katman to make this site recommendable by ChatGPT.”

## 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](https://katman.pro/app/login) → **MCP**. The steps are below.
-   **Optional: an OpenRouter API key,** with some credit, for automated visibility runs. Create one at [openrouter.ai/keys](https://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:

```bash
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](https://code.claude.com/docs/en/mcp)). 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](https://katman.pro/mcp):

```json
{
  "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](https://code.visualstudio.com/docs/copilot/reference/mcp-configuration)):

```json
{
  "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

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

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

### Gemini CLI

```bash
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](https://katman.pro/app/login) and open **Billing**, or start from the [pricing page](https://katman.pro/pricing).
    -   **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](https://katman.pro/docs/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](https://katman.pro/docs/permissions).

## Add your OpenRouter key (optional)

1.  Create a key at [openrouter.ai/keys](https://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](https://katman.pro/docs/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:

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

| File | Written by | What’s in it |
| --- | --- | --- |
| `research.json`, `research.md` | `katman_research` | Brand, one sentence, not-X note, situations, competitors, proof, keywords, question set |
| `config.json` | several tools | Site URL, language, models, temperature, IndexNow key |
| `scan.json` | `katman_scan_code` | Codebase scan |
| `audits/<time>.json`, `audit.md` | `katman_audit_site` | Live audit results |
| `runs/<time>.json`, `measurements.md` | `katman_visibility_run`, `katman_manual_check` | Visibility runs and the measurement table |
| `plan.json`, `plan.md` | `katman_plan` | Page plan and tasks with P-codes and acceptance criteria; ticked boxes survive a regenerate |
| `indexnow.json` | `katman_indexnow` | URLs submitted, with their lastmod |
| `report.md` | `katman_report` | A shareable report |
| `log.md` | every tool that writes | A dated history of what Katman did |
| `cache/` | visibility tools | OpenRouter model prices, kept for 24 hours |

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:

```bash
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](https://katman.pro/docs/tools).
-   What Katman reads, writes and sends: [Permissions](https://katman.pro/docs/permissions).
-   Questions, models, costs and why one run is a small sample: [Visibility runs](https://katman.pro/docs/visibility-runs).
-   If the server doesn’t show up or a tool fails: [Troubleshooting](https://katman.pro/docs/troubleshooting).

## Frequently asked questions

### Do I need a Katman key to start?

Yes. Every tool except katman\_account needs KATMAN\_KEY. Buy Audit Week ($3 once, for 7 days) or Katman Pro, then create the key in your account at katman.pro/app → MCP. Audit Week finds what’s wrong and tells you what to do; building pages and writing files is Pro.

### Do I need an OpenRouter key to start?

No. Only automated visibility runs use it; add the key later, when you want to measure.

### Where should I run Katman from?

From your website’s project folder, the one with package.json or index.html. Katman uses the folder you pass as project\_root, then KATMAN\_PROJECT\_ROOT, then the root your editor reports, then the current folder.

### Does Katman work with Lovable, Bolt, v0 or Replit?

Yes, through a local copy: sync the project to GitHub, clone it and open it in Cursor, Claude Code or VS Code. The live-site audit works on any public URL.

### Is it safe to commit the .katman folder?

Yes. It holds research, audits, runs and the plan, never secrets, and committing it keeps a dated history of what changed.

### How do I get a newer version?

Use npx -y katman-mcp@latest in your client’s config and restart the MCP server; npx may otherwise reuse a cached copy.

## Related pages

-   [**Tools reference** Reference for all 17 Katman MCP tools: what each one does, whether it needs Audit Week or Pro, its key inputs, what it writes, and an example call to copy.](https://katman.pro/docs/tools)
-   [**Permissions: what Katman can do** What Katman reads in your project, what it writes, which network calls it makes and when, what goes to katman.pro with your key, and how it handles your keys.](https://katman.pro/docs/permissions)
-   [**Visibility runs** How Katman measures AI visibility: 12+2 question set, five assistants via OpenRouter, cost caps, manual checks in the apps, and why one run is a small sample.](https://katman.pro/docs/visibility-runs)
-   [**Troubleshooting** Fixes for common Katman problems: server not showing up, wrong project folder, missing keys, locked tools, 402 errors, Cloudflare challenges, empty pages.](https://katman.pro/docs/troubleshooting)
-   [**Katman MCP** Katman MCP runs in Cursor, Claude Code and VS Code: it scans your code, audits your live site like AI crawlers do and checks every fix. Audit Week: $3, 7 days.](https://katman.pro/mcp)
-   [**Pricing** Audit Week costs $3 once for 7 days of Katman's audit and recommendation tools. Katman Pro adds the build tools, the course and the community: $29/month.](https://katman.pro/pricing)

Updated 30 September 2026 · Katman