clarity-mcp-multi

An MCP proxy that adds per-client token routing on top of Microsoft's official Clarity MCP server.

Why

The official server authenticates with a single Clarity Data Export token, and a token maps to exactly one project. If you manage several Clarity projects you end up editing the config and restarting the client every time you switch project.

This proxy keeps a name → token map and resolves the token by name at runtime. It does not reimplement any Clarity functionality: it launches the official server as a child process and forwards calls to it, so it inherits the full tool set and tracks upstream changes automatically.

How it works

The package acts as a server towards its MCP client (Claude, Cursor, …) and as a client towards the official server at the same time. It registers two tools of its own and re-exports whatever the official server exposes. A call that isn't one of its own tools is forwarded to the child process and the response is returned unchanged.

Selecting a client with clarity_usa_cliente restarts the child with that client's token. The token is read from the registry on the server side and is never sent through the conversation.

The child is launched as @microsoft/clarity-mcp-server@latest, so upstream releases are picked up without changes here.

Configuration

{
  "mcpServers": {
    "clarity": {
      "command": "npx",
      "args": ["-y", "clarity-mcp-multi@latest"],
      "env": {
        "CLARITY_TOKENS": "{\"acme\":\"<token>\",\"globex\":\"<token>\"}"
      }
    }
  }
}

CLARITY_TOKENS is a JSON object mapping a client name to its Clarity Data Export token (Clarity → Settings → Data export). As an alternative, set CLARITY_TOKENS_FILE to a path holding the same JSON. CLARITY_DEFAULT_CLIENT optionally sets the client selected at startup.

Keep tokens out of source control: pass them through the environment or a file the host loads, not in a committed config.

Tools

Tool	Description
clarity_clienti	Lists the configured client names and the active one. No token is returned.
clarity_usa_cliente	Sets the active client by name; subsequent calls use its token.

Names are matched case-insensitively. Every other tool is proxied to the official server under the active client's token.

Requirements

Node.js 18 or later. One Clarity Data Export token per project.

License

MIT