Clarity MCP Server

A Model Context Protocol (MCP) server for interacting with the Clarity API. This server enables Cursor and other MCP-compatible clients to access Clarity backend services.

Installation

Prerequisites

• Python 3.10 or higher (required for fastmcp)
• uv package manager (recommended for this project)

Installing uv

On macOS (using Homebrew):

brew install uv

On Linux/macOS (using curl):

curl -LsSf https://astral.sh/uv/install.sh | sh

On Windows:

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Setting up the project

Once uv is installed, it will automatically manage Python versions. You can install dependencies and run the server:

# Install dependencies (uv will automatically use Python 3.10+)
# IMPORTANT: Run this WITHOUT activating any venv - just run it directly
uv sync

# Install the package in editable mode so the 'clarity-mcp' command is available
# This makes the entrypoint script available
uv pip install -e .

# Verify the installation worked
uv run which clarity-mcp

# Run the server locally (for development)
uv run clarity-mcp

Important Notes:

• Never activate the venv manually - just run uv sync and uv run directly in your shell
• uv sync creates a .venv directory automatically, but you never need to activate/deactivate it
• uv pip install -e . installs the package in editable mode, making the clarity-mcp command available
• uv run automatically uses the venv that uv manages - this is "no manual virtualenv management"
• uvx clarity-mcp will only work after the package is published to PyPI. For local development, use uv run clarity-mcp after running uv sync and uv pip install -e .

The server will run over stdio and communicate with MCP clients.

Configuration

The server requires the following environment variables:

• CLARITY_EMAIL (required): Your Clarity account email address
• CLARITY_PASSWORD (required): Your Clarity account password
• CLARITY_BASE_URL (optional): Base URL for the Clarity API (defaults to https://clarity-backend.up.railway.app/)
• CLARITY_FRONTEND_URL (optional): Frontend URL for the Clarity Chat API (defaults to https://clarity-frontend.up.railway.app)

Setting Environment Variables

You can set environment variables in several ways:

Option 1: Export in your shell

export CLARITY_EMAIL=your_email@example.com
export CLARITY_PASSWORD=your_password
uv run clarity-mcp

Option 2: Use a .env file (with python-dotenv) Create a .env file in your working directory:

CLARITY_EMAIL=your_email@example.com
CLARITY_PASSWORD=your_password
CLARITY_BASE_URL=https://clarity-backend.up.railway.app/
CLARITY_FRONTEND_URL=https://clarity-frontend.up.railway.app

Option 3: Inline with the command

CLARITY_EMAIL=your_email@example.com CLARITY_PASSWORD=your_password uv run clarity-mcp

Cursor MCP Configuration

Add the following entry to your Cursor mcp.json configuration file:

{
  "mcpServers": {
    "clarity": {
      "command": "uvx",
      "args": ["clarity-mcp"],
      "env": {
        "CLARITY_EMAIL": "your_email@example.com",
        "CLARITY_PASSWORD": "your_password",
        "CLARITY_BASE_URL": "https://clarity-backend.up.railway.app/",
        "CLARITY_FRONTEND_URL": "https://clarity-frontend.up.railway.app"
      }
    }
  }
}

Note:

• Replace your_email@example.com and your_password with your actual Clarity credentials
• The CLARITY_BASE_URL and CLARITY_FRONTEND_URL are optional

After adding this configuration, restart Cursor to load the MCP server.

Available Tools

clarity_ping

Health check tool for the Clarity MCP server.

• Input: None
• Output: {"status": "ok"}

get_company_info

Get company information from the Clarity API.

• Input: None
• Output: Dictionary containing company information
• Errors: Raises ClarityAPIError if the API request fails

get_insights

Get insights from the Clarity API.

• Input:
  • status (optional): Status filter. Can be a single status (e.g., "new") or comma-separated multiple statuses (e.g., "new,ticket_created"). If not provided, returns all insights.
• Output: Dictionary containing insights data
• Errors: Raises ClarityAPIError if the API request fails

Examples:

• Get all insights: get_insights()
• Get only new insights: get_insights(status="new")
• Get new and ticket_created insights: get_insights(status="new,ticket_created")

chat

Ask questions about your users and their feedback using natural language.

• Input:
  • query (required): Natural language question about user feedback
• Output: Dictionary containing the chat response with a response field
• Errors: Raises ClarityAPIError if the API request fails

Use this tool when you need to understand what users are saying about specific topics, find related feedback, or explore user sentiment.

Examples:

• chat(query="What are users saying about onboarding?")
• chat(query="Where else are users reporting this problem?")
• chat(query="What are the main complaints about the mobile app?")
• chat(query="How do users feel about the new pricing?")

Authentication

Note: This server currently uses email/password authentication, which is a temporary MVP approach. The architecture is designed to allow swapping authentication methods (e.g., API keys or OAuth) in the future without changing the MCP tool interface.