Skip to main content
Query your Surfa analytics with natural language through Claude Desktop.

​
Prerequisites

Get your Surfa API key from your dashboard.

​
Step 1: Install the MCP Server

Clone the Surfa MCP repository: 
git clone https://github.com/gamladz/surfa-mcp.git
cd surfa-mcp
Create a virtual environment and install dependencies: 
uv venv
uv pip install -e .
The -e flag installs in editable mode, so you can update the code later with git pull.

​
Step 2: Find Your uv Path

You’ll need the full path to uv for the Claude Desktop config. macOS/Linux: 
which uv
Common paths:
  • /Users/yourname/.local/bin/uv (macOS)
  • /home/yourname/.local/bin/uv (Linux)
  • /opt/homebrew/bin/uv (macOS with Homebrew)
Use the full absolute path, not just uv. Claude Desktop needs the complete path.

​
Step 3: Configure Claude Desktop

Find your Claude Desktop config file: macOS: 
~/Library/Application Support/Claude/claude_desktop_config.json
Windows: 
%APPDATA%\Claude\claude_desktop_config.json
Linux: 
~/.config/Claude/claude_desktop_config.json
Open the file and add the Surfa MCP server: 
{
  "mcpServers": {
    "surfa": {
      "command": "/Users/yourname/.local/bin/uv",
      "args": [
        "--directory",
        "/Users/yourname/path/to/surfa-mcp",
        "run",
        "surfa-mcp"
      ],
      "env": {
        "SURFA_API_KEY": "sk_live_your_key_here",
        "SURFA_API_URL": "https://surfa-web.vercel.app"
      }
    }
  }
}
Replace these values:
  • /Users/yourname/.local/bin/uv → Your actual uv path from Step 2
  • /Users/yourname/path/to/surfa-mcp → Your actual clone directory
  • sk_live_your_key_here → Your Surfa API key

​
If You Have Other MCP Servers

If you already have MCP servers configured, just add Surfa to the existing mcpServers object: 
{
  "mcpServers": {
    "existing-server": {
      "command": "...",
      "args": [...]
    },
    "surfa": {
      "command": "/Users/yourname/.local/bin/uv",
      "args": [
        "--directory",
        "/Users/yourname/path/to/surfa-mcp",
        "run",
        "surfa-mcp"
      ],
      "env": {
        "SURFA_API_KEY": "sk_live_your_key_here",
        "SURFA_API_URL": "https://surfa-web.vercel.app"
      }
    }
  }
}

​
Step 4: Restart Claude Desktop

Important: You must completely quit and reopen Claude Desktop for changes to take effect. macOS:
  1. Cmd+Q to quit Claude Desktop
  2. Reopen from Applications
Windows:
  1. Right-click system tray → Quit
  2. Reopen from Start menu

​
Step 5: Verify Connection

Look for the 🔌 icon in the bottom-right corner of Claude Desktop. Click it to see connected MCP servers. You should see “surfa” in the list.
MCP Icon in Claude Desktop

​
Step 6: Test Your First Query

Ask Claude: 
Show me my Surfa analytics overview
You should get a response like: 
Your Surfa analytics:
- Total Sessions: 35
- Success Rate: 85%
- Average Execution Time: 245ms
- Active Sessions: 2
Success! Your Surfa MCP Server is now connected and working.

​
Example Queries

Try these queries to explore your analytics: 
"Show me my Surfa analytics overview"

​
Troubleshooting

Check:
  1. Config file path is correct
  2. JSON syntax is valid (use jsonlint.com)
  3. No trailing commas in JSON
  4. File saved after editing
Debug: Check Claude Desktop logs:
# macOS
tail -f ~/Library/Logs/Claude/mcp*.log

# Windows
type %APPDATA%\Claude\Logs\mcp*.log
Check:
  1. uv path is correct (run which uv again)
  2. Surfa MCP directory path is absolute, not relative
  3. API key is correct (check dashboard)
  4. Internet connection is working
Test manually:
cd /path/to/surfa-mcp
export SURFA_API_KEY=sk_live_your_key
export SURFA_API_URL=https://surfa-web.vercel.app
uv run surfa-mcp
If this works, the issue is in your Claude Desktop config.
Check:
  1. You have events in your Surfa dashboard
  2. API key has access to the workspace
  3. Events are from “live” source (not test data)
Verify: Go to your dashboard and confirm you see events.
Solution: Reinstall dependencies:
cd /path/to/surfa-mcp
uv pip install -e .
Then restart Claude Desktop.
Common mistakes:
  • Trailing comma after last item
  • Missing quotes around strings
  • Backslashes in Windows paths (use forward slashes or double backslashes)
Fix: Copy your config to jsonlint.com to validate.Example of valid JSON:
{
  "mcpServers": {
    "surfa": {
      "command": "/path/to/uv",
      "args": ["--directory", "/path/to/surfa-mcp", "run", "surfa-mcp"],
      "env": {
        "SURFA_API_KEY": "sk_live_key",
        "SURFA_API_URL": "https://surfa-web.vercel.app"
      }
    }
  }
}

​
Advanced Configuration

​
Using Production API

If you’re using the production Surfa API (not localhost): 
{
  "env": {
    "SURFA_API_KEY": "sk_live_your_key_here",
    "SURFA_API_URL": "https://surfa.dev"
  }
}

​
Custom Timeout

Set a custom timeout (in seconds): 
{
  "env": {
    "SURFA_API_KEY": "sk_live_your_key_here",
    "SURFA_API_URL": "https://surfa-web.vercel.app",
    "SURFA_TIMEOUT": "60"
  }
}

​
Multiple Workspaces

Use different API keys for different workspaces: 
{
  "mcpServers": {
    "surfa-production": {
      "command": "/path/to/uv",
      "args": ["--directory", "/path/to/surfa-mcp", "run", "surfa-mcp"],
      "env": {
        "SURFA_API_KEY": "sk_live_prod_key",
        "SURFA_API_URL": "https://surfa.dev"
      }
    },
    "surfa-staging": {
      "command": "/path/to/uv",
      "args": ["--directory", "/path/to/surfa-mcp", "run", "surfa-mcp"],
      "env": {
        "SURFA_API_KEY": "sk_live_staging_key",
        "SURFA_API_URL": "https://staging.surfa.dev"
      }
    }
  }
}

​
Updating the MCP Server

To update to the latest version: 
cd /path/to/surfa-mcp
git pull
uv pip install -e .
Then restart Claude Desktop.

​
Uninstalling

To remove the Surfa MCP Server:
  1. Remove the "surfa" entry from claude_desktop_config.json
  2. Restart Claude Desktop
  3. Optionally delete the cloned directory: 
    rm -rf /path/to/surfa-mcp

​
Next Steps

MCP Server Overview

Learn about all 4 analytics tools and example queries

API Reference

Complete API documentation with examples

Quickstart Guide

Start tracking events in 5 minutes

GitHub Repository

View source and contribute

​
Need Help?

Join Discord

Get help from the community and Surfa team