# clarity-mcp-server

**Repository Path**: mirrors_microsoft/clarity-mcp-server

## Basic Information

- **Project Name**: clarity-mcp-server
- **Description**: A Model Context Protocol server for Microsoft Clarity data export API
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-05-13
- **Last Updated**: 2025-09-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Microsoft Clarity Data Export MCP Server

This is a Model Context Protocol (MCP) server for the Microsoft Clarity data export API. It allows you to fetch analytics data from Clarity using Claude for Desktop or other MCP-compatible clients.

## Features

- Query Microsoft Clarity analytics data through a simple interface
- Filter by up to 3 dimensions (Browser, Device, Country/Region, OS, etc.)
- Retrieve various metrics (Scroll Depth, Engagement Time, Traffic, etc.)
- Seamlessly integrates with Claude for Desktop and other MCP clients

## Setup and Installation

### Prerequisites

- Node.js v16 or higher
- A Microsoft Clarity account and API token
- Any MCP-compatible client (Claude for Desktop, etc.)

### Installation

#### Option 1: Install via npm (recommended)

You can install and run this package directly using npm:

```bash
# Install globally
npm install -g @microsoft/clarity-mcp-server

# Run the server
clarity-mcp-server
```

#### Option 2: Run with npx without installing

You can run the server directly using npx without installing:

```bash
npx @microsoft/clarity-mcp-server
```

With either option, you can provide your Clarity API token using the `--clarity_api_token` parameter:

```bash
npx @microsoft/clarity-mcp-server --clarity_api_token=your-token-here
```

#### Option 3: Manual Installation

1. Clone or download this repository
2. Install dependencies:
   ```
   npm install
   ```
3. Build the TypeScript code:
   ```
   npm run build
   ```
4. Run the server:
   ```
   npm start
   ```
### Extension/Plugin Installation 

#### Visual Studio Code Extension

[<img src="https://img.shields.io/badge/VS_Code-VS_Code?style=flat-square&label=Install+Server&color=0098FF" alt="Install in VS Code">](https://insiders.vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522clarity-server%2522%252C%2522command%2522%253A%2522npx%2522%252C%2522args%2522%253A%255B%2522%2540microsoft%252Fclarity-mcp-server%2522%255D%257D) 

Click the button above to install the Microsoft Clarity MCP server directly in Visual Studio Code.

#### Claude Desktop Plugin
Install from Claude's extension gallery:
1. Open **Claude Desktop**.
2. Navigate to **File → Settings → Extensions**. 
3. Search for **Microsoft Clarity MCP Server**.
4. Click **Install** to add the extension.
5. Configure your **API Token**.<br>
Follow the instructions in the [API Token section](https://github.com/microsoft/clarity-mcp-server#api-token) to retrieve and set it up correctly.

## Configuration

You can provide the [Clarity data export API](https://learn.microsoft.com/en-us/clarity/setup-and-installation/clarity-data-export-api) token in two ways:

1. **Command Line Arguments**:
   ```bash
   npx @microsoft/clarity-mcp-server --clarity_api_token=your-token
   ```

2. **Tool Parameters**:
   - Provide `token` as a parameter when calling the `get-clarity-data` tool

## Configuring MCP Clients

### Generic MCP Client Configuration

MCP clients typically require configuration to connect to the server. Here's a general example of how to configure an MCP client:

```json
{
  "mcpServers": {
    "@microsoft/clarity-mcp-server": {
      "command": "npx",
      "args": [
        "@microsoft/clarity-mcp-server",
        "--clarity_api_token=your-api-token-here"
      ]
    }
  }
}
```

The specifics of where and how to add this configuration will depend on your specific MCP client.

### Claude for Desktop Configuration

To configure Claude for Desktop to use this server:

1. Open your Claude for Desktop configuration file:
   - **Windows**: `%AppData%\Claude\claude_desktop_config.json`
   - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`

2. Add the configuration shown in the generic example above

3. Save the configuration file and restart Claude for Desktop

## Using the Server

When using an MCP client with this server configured, you can ask it to fetch Clarity data. For example:

"Can you fetch my Clarity data for the last day, filtered by Browser and showing Traffic metrics?"

The MCP client will then prompt you to run the `get-clarity-data` tool, which requires:
- `numOfDays`: Number of days to retrieve (1-3)
- `dimensions`: Array of dimensions to filter by (optional)
- `metrics`: Array of metrics to retrieve (optional)

If you haven't configured your credentials via command-line arguments, you'll also need to provide:
- `token`: Your Clarity API token

## API Token

### Getting Your API Token

To generate an API token:

1. Go to your Clarity project
2. Select Settings → Data Export → Generate new API token
3. Provide a descriptive name for the token
4. Save the generated token securely

## Limitations

- Maximum of 10 API requests are allowed per project per day
- Data retrieval is confined to the previous 1 to 3 days
- Maximum of three dimensions can be passed in a single request
- The response is limited to 1,000 rows and can't be paginated

## License

MIT