Hotjar Mcp Server

Hotjar MCP Server

A Model Context Protocol (MCP) server for Hotjar - the user behavior analytics and feedback collection tool. This server enables AI assistants to interact with Hotjar surveys through the MCP protocol.

Features

• 🔌 Dual Transport Support: Works with both SSE (Server-Sent Events) and stdio transports
• 📊 Survey Management: Retrieve surveys for specific Hotjar sites
• 📝 Survey Details: Get detailed information for individual surveys
• 💬 Survey Responses: Fetch survey responses with pagination support
• 🔐 Secure Authentication: OAuth client credentials authentication with token caching
• ⚡ Performance Optimized: Built-in token caching for improved performance
• 🛡️ Error Handling: Comprehensive error handling for authentication and rate limits

Configuration

Authentication Setup

1. You need to get Hotjar OAuth credentials:

• Log in to your Hotjar account
• Navigate to Settings → Integrations → API
• Create a new OAuth application or use existing credentials
• Copy your Client ID and Client Secret

1. Configure environment variables:

• HOTJAR_CLIENT_ID: Your Hotjar Client ID
• HOTJAR_CLIENT_SECRET: Your Hotjar Client Secret
• HOTJAR_SITE_ID: Your Hotjar site ID (optional, can be passed as parameter)
• HOTJAR_SURVEY_ID: Your Hotjar survey ID (optional, can be passed as parameter)

1. Alternative: Pass credentials directly as tool parameters instead of using environment variables

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | HOTJAR_CLIENT_ID | Optional | Your Hotjar OAuth Client ID | | HOTJAR_CLIENT_SECRET | Optional | Your Hotjar OAuth Client Secret | | HOTJAR_SITE_ID | Optional | Default Hotjar site ID | | HOTJAR_SURVEY_ID | Optional | Default Hotjar survey ID | | PORT | Optional | Server port (default: 3001, only for SSE mode) | | LOG_LEVEL | Optional | Logging level: debug, info, warn, error (default: info) | | MCP_TRANSPORT | Optional | Transport mode: "sse" or "stdio" (default: sse) |

*Credentials can be passed as tool parameters instead of environment variables.

Usage

Local Usage

1. Copy the example environment file and configure your credentials:

cp .env.example .env

1. Edit .env file with your Hotjar credentials:

HOTJAR_CLIENT_ID=your_client_id
HOTJAR_CLIENT_SECRET=your_client_secret
HOTJAR_SITE_ID=your_site_id

1. Start the server:

npm start

The server will start on http://localhost:3001 with the following endpoints:

• GET /sse - SSE connection endpoint
• POST /messages?sessionId= - Message handling endpoint
• GET /health - Health check endpoint

Deploy anywhere

You can also dockerize this application for deployment. Create your own Dockerfile and deploy as needed.

Stdio Mode

For use with MCP clients that support stdio transport:

npm start -- --stdio

Or set the environment variable:

MCP_TRANSPORT=stdio npm start

Client Configuration

Cursor IDE

Add to your Cursor settings (.cursor/mcp.json):

SSE Mode:

{
  "mcpServers": {
    "hotjar": {
      "url": "http://localhost:3001/sse"
    }
  }
}

Stdio Mode:

{
  "mcpServers": {
    "hotjar": {
      "command": "node",
      "args": ["/path/to/hotjar-mcp-server/build/index.js", "--stdio"],
      "env": {
        "HOTJAR_CLIENT_ID": "your_client_id",
        "HOTJAR_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}

Claude Desktop

Add to your Claude Desktop config (claude_desktop_config.json):

{
  "mcpServers": {
    "hotjar": {
      "command": "node",
      "args": ["/path/to/hotjar-mcp-server/build/index.js", "--stdio"],
      "env": {
        "HOTJAR_CLIENT_ID": "your_client_id",
        "HOTJAR_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}

Tools

getHotjarSurveys

Get surveys for a specific Hotjar site.

Parameters: | Name | Type | Required | Description | |------|------|----------|-------------| | clientId | string | Optional | Hotjar Client ID (uses env var if not provided) | | clientSecret | string | Optional | Hotjar Client Secret (uses env var if not provided) | | siteId | string | Optional | Hotjar site ID (uses env var if not provided) | | cursor | string | Optional | Pagination cursor from previous response |

Example:

{
  "siteId": "1234567"
}

getHotjarSurveyDetails

Get detailed information for a specific Hotjar survey.

Parameters: | Name | Type | Required | Description | |------|------|----------|-------------| | clientId | string | Optional | Hotjar Client ID | | clientSecret | string | Optional | Hotjar Client Secret | | siteId | string | Optional | Hotjar site ID | | surveyId | string | Required* | Hotjar survey ID |

Example:

{
  "siteId": "1234567",
  "surveyId": "9876543"
}

getHotjarSurveyResponses

Get responses for a specific Hotjar survey.

Parameters: | Name | Type | Required | Description | |------|------|----------|-------------| | clientId | string | Optional | Hotjar Client ID | | clientSecret | string | Optional | Hotjar Client Secret | | siteId | string | Optional | Hotjar site ID | | surveyId | string | Required* | Hotjar survey ID | | cursor | string | Optional | Pagination cursor from previous response |

Example:

{
  "siteId": "1234567",
  "surveyId": "9876543",
  "cursor": null
}

Pagination

Both getHotjarSurveys and getHotjarSurveyResponses support pagination:

• First request: Omit the cursor parameter or pass null
• Subsequent requests: Use the next_cursor value from the previous response
• End of results: When next_cursor is null in the response, there are no more results

Error Handling

The server handles the following error types:

• Authentication Errors: Invalid or expired credentials
• Rate Limit Errors: Too many requests (includes reset time)
• Validation Errors: Missing required parameters
• API Errors: General Hotjar API errors

License

MIT License - Copyright (c) 2026 Yasin Uysal - see [LICENSE](LICENSE) for details.

Disclaimer

This project is not affiliated with, endorsed by, or sponsored by Hotjar Ltd. Users are responsible for complying with Hotjar's API Terms of Service and Terms of Service.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: yasin749
• Source: yasin749/hotjar-mcp-server
• License: MIT

Install and usage instructions live in the source repository linked above.