Skip to content

clarity-api

Microsoft Clarity API + MCP Server + A2A Agent for the agent-utilities ecosystem — a typed, action-routed connector for the Clarity Data Export API.

Official documentation

This site is the canonical reference for clarity-api, maintained alongside every release.

PyPI MCP Server License GitHub

Overview

clarity-api wraps the Microsoft Clarity Data Export API with typed, deterministic MCP tools and an optional Pydantic-AI agent server. It provides:

  • Api — a Python client (clarity_api.api_client.Api) composed from per-domain mixins. It validates credentials against GET /projects and exposes get_data_export for live dashboard insights.
  • Action-routed MCP tool — the consolidated, togglable clarity_insights tool (CONCEPT:CLA-001) that minimizes token overhead in LLM contexts.
  • An A2A agent server — a Pydantic-AI graph agent (console script clarity-agent) that calls the MCP tool surface and exposes an AG-UI web interface.

The connector remains inactive when credentials are absent: configure CLARITY_URL and CLARITY_TOKEN to connect it to your Clarity project.

Explore the documentation

  • Installation — pip, source, extras, and the prebuilt Docker image.
  • Deployment — run the MCP and agent servers, Docker Compose.
  • Usage — the MCP tools, the Api client, and the CLI.
  • Overview — the action-routed tool surface and architecture.
  • Concepts — the CONCEPT:CLA-* registry.

Quick start

pip install "clarity-api[mcp]"
clarity-mcp                        # stdio MCP server (default transport)

Connect it to a Clarity project:

export CLARITY_URL=https://www.clarity.ms
export CLARITY_TOKEN=<your-clarity-token>
clarity-mcp --transport streamable-http --host 0.0.0.0 --port 8000

See Installation and Deployment for the full matrix (PyPI extras, Docker image, all transports, the agent server).