clarity-mcp 0.2.5
A Model Context Protocol (MCP) server for interacting with the Clarity API
License: MIT
Requires Python: >=3.10
Keywords: ai, api, clarity, mcp, model-context-protocol

# 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):**
```bash
brew install uv
```

**On Linux/macOS (using curl):**
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

**On Windows:**
```powershell
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:

```bash
# 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**
```bash
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**
```bash
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:

```json
{
  "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.