Skip to main content
Glama
@clikta/mcp-server

@clikta/mcp-server

by rscoelho

@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.

Requires a Pro or Team Clikta plan. A free-plan token gets a clear plan_required error from clikta_start_recording explaining that, rather than a bare auth failure.

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: Glance

Environment variables

Variable

Required

Default

Description

CLIKTA_API_TOKEN

yes

—

Generated in Settings → API Token

CLIKTA_API_URL

no

https://clikta.com

Point at a self-hosted instance if you run one

CLIKTA_MCP_HEADLESS

no

false

Set "true" to run Chromium headless (CI/scripted use). Headed by default so you can watch the demo happen live

Tools

Tool

What it does

clikta_start_recording

Creates a recording, launches the browser, optionally navigates to toolUrl

clikta_navigate

Go to a URL, logs a navigate step

clikta_click

Click an element (by role/name, text, or CSS selector), logs a click step. Refuses destructive-looking targets (delete/pay/confirm purchase/...) unless confirm: true

clikta_type

Fill a field, logs an input step

clikta_note

Explain why you did something — feeds the AI guide generator the same way a human's spoken narration does. Use this liberally, it's the highest-leverage tool here

clikta_screenshot

Ad-hoc screenshot saved to the Clikta screenshot library

clikta_finish_recording

Marks the recording done, generates the AI guide, publishes it, returns the share link, closes the browser

clikta_list_recordings

Lists existing recordings, to resume or avoid duplicates

clikta_list_tools

Lists registered Clikta "Tool" entities (products), to attach a recording to an existing one via toolId

clikta_create_tool

Registers a new product/tool, so future recordings can attach to it via toolId

clikta_describe_tool

Read-only summary of what Clikta already knows about a product: its modules/chapters, past recordings and their steps, pages visited before

clikta_plan_demo

Turns an objective into a short step outline before recording — pre-processing for a single demo

clikta_plan_module

Proposes a MODULE — a set of 3-8 separate demos covering a broader goal — as a plan only, nothing saved

clikta_create_module

Persists a module and its planned chapters, once the user has approved the clikta_plan_module proposal

clikta_list_modules

Lists a product's modules, with chapter counts

clikta_get_module

Full per-chapter detail of one module — which chapters are recorded vs still pending, to resume across sessions

Typical flow

For a single, self-contained demo:

  1. clikta_list_tools / clikta_create_tool — find or register the product

  2. clikta_describe_tool and clikta_plan_demo — see what's already known, then plan the steps

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

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

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

  6. clikta_finish_recording to generate and publish the guide

For a broader goal that's really several demos (e.g. "document the whole onboarding experience"):

  1. clikta_plan_module to propose a module (a name + 3-8 chapters) — show this to the user and get their explicit approval before continuing, this is the most important checkpoint in the whole flow

  2. clikta_create_module to persist it once approved

  3. For each chapter, follow the single-demo flow above, passing moduleId/chapterId to clikta_start_recording so the finished recording fills that slot

  4. clikta_get_module any time to check progress, including across separate sessions

The full server instructions (shown to the connecting client automatically) spell this out in more detail — see src/instructions.ts.

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

Available Tools

9 tools
clikta_clickA

Click an element in the active recording's browser and log it as a step. Locate the element with role(+name), text, or selector — role/text are more resilient than raw CSS. Refuses to click elements that look destructive (delete, payment, purchase confirmation, unsubscribe, ...) unless confirm:true.

Inputs: name, role, text, confirm, +1 more.

clikta_finish_recordingA

Stop the active recording, generate the AI guide/demo from the captured steps, publish it, and return the shareable link. Closes the browser.

Inputs: no named parameters.

clikta_list_recordingsA

List existing recordings in the Clikta workspace, so you can resume or avoid duplicating work.

Inputs: no named parameters.

clikta_list_toolsA

List the products/tools already registered in the Clikta workspace (Clikta 'Tool' entities, e.g. 'Acme Dashboard'), so a new recording can be attached to an existing one via toolId instead of creating a duplicate.

Inputs: no named parameters.

clikta_navigateA

Navigate the active recording's browser to a URL and log it as a step.

Inputs: url (required).

clikta_noteA

Explain, in your own words, why you just did (or are about to do) something. This is the single most valuable tool here: notes feed the same mechanism as a human's spoken narration, and Clikta's AI guide generator uses them as context for writing each step's description. Call it liberally.

Inputs: text (required).

clikta_screenshotA

Take an ad-hoc screenshot of the current page and save it to the Clikta screenshot library (not tied to a recording step).

Inputs: title.

clikta_start_recordingA

Start a new Clikta recording. Creates the recording on the Clikta workspace, launches a real browser, and (if toolUrl is given) navigates there first. Call this before any other clikta_* action tool. Prefer a staging/sandbox toolUrl over production when one is available — the result includes a warning if the URL doesn't look like one.

Inputs: name (required), toolId, toolUrl, objective.

clikta_typeA

Fill a text field in the active recording's browser and log it as a step.

Inputs: value (required), name, role, text, +1 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.2/5.0

    Scored across 9 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: navigation, recording control, interaction (click/type), annotation (note), capture (screenshot), and listing queries. There is no overlap or ambiguity between tool roles.

    Naming Consistency5/5

    All tools follow a consistent snake_case pattern, with verbs like start, finish, click, type, list, and screenshot. The clikta_ prefix unifies the namespace, and naming is predictable across the entire set.

    Tool Count5/5

    With 9 tools, the server is well-scoped for its purpose—recording browser sessions and generating guides. Each tool fills a necessary role in the workflow, with no clutter or redundancy.

    Completeness4/5

    The tool set covers the full lifecycle of creating a recording: start, navigate, interact, annotate, screenshot, and finish with publishing. Minor gaps exist, such as no update/delete for recordings, but these are not core to the stated purpose.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Lets Claude Code drive your own Chrome browser with human-like clicks, drags, and typing. It uses your real sessions and logins, and pauses for your confirmation on anything irreversible.
      8
      MIT
    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables Claude Code to drive a real browser, so you can navigate, click, type, screenshot, and run multi-step test scenarios with assertions, visual regression, and console/network monitoring straight from the terminal.
      106 npm
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Lets Claude Desktop drive a real browser to execute plain-English goals as recorded walkthroughs, capturing HD video, per-step screenshots and a pass/fail action log. It also turns those recordings into written user guides, how-to articles and FAQs without any selectors or scripts to maintain.
      MIT
    • A
      license
      Not graded
      quality
      A
      maintenance
      Gives Claude Code a real browser so it can navigate, click, type, screenshot, and assert against web pages directly from the terminal. Enables multi-step test scenarios, visual regression checks, session recording, and console/network error monitoring with security controls.
      106 npm
      MIT