@clikta/mcp-server

MCP server that lets Claude drive a real browser and turn what it does into a Clikta interactive demo, step-by-step guide, and narrated video — automatically. No manual clicking, no Chrome extension required.

It reuses the exact same pipeline as the Clikta Chrome extension: every action is posted as an Event to your Clikta workspace, and clikta_finish_recording triggers the same AI guide generator that turns a human's recording into steps.

Built by Clikta — the design rationale and implementation history live in docs/mcp-architecture.md in the main clikta repo.

Setup

1. Get an API token: in the Clikta web app, go to Settings → API Token and generate one (clikta_...). This is the same token type the Chrome extension uses.

2. Install Playwright's Chromium browser (runs automatically on npm install via postinstall, but you can re-run it manually):

   npx playwright install chromium

3. Add the server to Claude Code (or any MCP host) — either via the CLI:

   claude mcp add clikta -- npx -y @clikta/mcp-server

   or by adding it to your .mcp.json:

   {
     "mcpServers": {
       "clikta": {
         "command": "npx",
         "args": ["-y", "@clikta/mcp-server"],
         "env": {
           "CLIKTA_API_URL": "https://clikta.com",
           "CLIKTA_API_TOKEN": "clikta_..."
         }
       }
     }
   }

Related MCP server: Browserbeam MCP Server

Environment variables

Tools

Typical flow

1. clikta_start_recording with a name and toolUrl pointing at the product/page to demo

2. Open the returned watchUrl in a browser to watch steps land live

3. clikta_navigate / clikta_click / clikta_type through the flow, calling clikta_note to explain intent along the way

4. clikta_finish_recording to generate and publish the guide

Guardrails

• Never click through payments, deletions, or other irreversible actions without the user's explicit go-ahead — clikta_click blocks these by default (see src/locator.ts's destructive-label patterns) and requires confirm: true to proceed.

• clikta_start_recording warns (non-blocking, via a warning field in its result) when toolUrl's host doesn't look like a staging/sandbox environment — prefer pointing it at one when available.

• API calls retry transient failures (network errors, 408/409/429/5xx) up to 3 times with backoff; real client errors (401/404/400/...) fail immediately since retrying won't help.

• Screenshots may capture whatever is on the page, including sensitive data — same disclosure as the Chrome extension's privacy policy applies here.

Development

npm install
npm run build   # tsc -> dist/
npm run dev      # tsc --watch

Manual test scripts

Both spawn the built server and drive it through the real MCP client protocol (@modelcontextprotocol/sdk's Client + StdioClientTransport), not a shortcut import of the tool functions. Need a real Clikta instance and an API token — generate one from Settings → API Token in the Clikta web app (or, if you also have the main clikta repo checked out, node scripts/mint-api-token.mjs you@example.com there mints one directly against the dev DB without going through the login UI).

CLIKTA_API_URL=http://localhost:3000 CLIKTA_API_TOKEN=clikta_... node scripts/e2e-test.mjs        # happy-path pipeline
CLIKTA_API_URL=http://localhost:3000 CLIKTA_API_TOKEN=clikta_... node scripts/guardrail-test.mjs   # destructive-click block + sandbox warning