@datafast/mcp-server

@datafast/mcp-server

An MCP (Model Context Protocol) server that exposes DataFast analytics as tools for AI assistants like Claude, Cursor, and others.

Ask your AI assistant questions like:

• "How many visitors did I get this week?"
• "What are my top referrers this month?"
• "Show me revenue by country for Q4"
• "Which pages have the highest conversion rate?"
• "What's my real-time visitor count?"

Requirements

• Node.js 18.0.0 or later
• A DataFast account with an API key

Setup

1. Get your API key

Go to your DataFast dashboard → Settings → API Keys and create a new key.

2. Install

npm install @datafast/mcp-server

3. Configure your AI client

Cursor

Add this to your .cursor/mcp.json:

{
  "mcpServers": {
    "datafast": {
      "command": "npx",
      "args": ["-y", "@datafast/mcp-server"],
      "env": {
        "DATAFAST_API_KEY": "df_your_api_key_here"
      }
    }
  }
}

Claude Desktop

Add this to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "datafast": {
      "command": "npx",
      "args": ["-y", "@datafast/mcp-server"],
      "env": {
        "DATAFAST_API_KEY": "df_your_api_key_here"
      }
    }
  }
}

Windsurf

Add this to your ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "datafast": {
      "command": "npx",
      "args": ["-y", "@datafast/mcp-server"],
      "env": {
        "DATAFAST_API_KEY": "df_your_api_key_here"
      }
    }
  }
}

Available Tools

Analytics

| Tool | Description | | --- | --- | | get_overview | High-level metrics: visitors, sessions, bounce rate, revenue, conversion rate | | get_timeseries | Time series data (hourly/daily/weekly/monthly) for trend analysis | | get_pages | Top pages by visitor count with revenue attribution | | get_referrers | Top traffic referrers with revenue attribution | | get_countries | Visitors and revenue by country | | get_cities | Visitors and revenue by city | | get_regions | Visitors and revenue by region/state | | get_browsers | Visitors and revenue by browser | | get_devices | Visitors and revenue by device type | | get_operating_systems | Visitors and revenue by OS | | get_campaigns | UTM campaign performance data | | get_goals | Goal completion data | | get_hostnames | Visitors and revenue by hostname | | get_realtime | Current real-time visitor count | | get_realtime_map | Real-time visitor locations with recent events | | get_metadata | Website metadata (domain, timezone, currency) |

Visitor Details

| Tool | Description | | --- | --- | | get_visitor | Detailed visitor profile with identity, activity, and conversion predictions |

Tracking

| Tool | Description | | --- | --- | | track_goal | Track a custom goal completion | | track_payment | Track a payment event for revenue attribution | | identify_visitor | Link a visitor to a user in your system |

Data Management

| Tool | Description | | --- | --- | | delete_goals | Delete goal events by date range, visitor, or goal name | | delete_payments | Delete payment events by transaction ID, visitor, or date range |

Filtering

All analytics tools support powerful filtering:

• UTM parameters: utm_source, utm_medium, utm_campaign, utm_term, utm_content
• Traffic sources: ref, source, via, referrer
• Content: page, entry_page, hostname
• Geography: country, region, city
• Technology: browser, os, device
• Date range: startAt, endAt (ISO 8601)
• Pagination: limit, offset
• Timezone: timezone (IANA format)

Environment Variables

| Variable | Required | Description | | --- | --- | --- | | DATAFAST_API_KEY | Yes | Your DataFast API key (starts with df_) | | DATAFAST_BASE_URL | No | API base URL (defaults to https://datafa.st) |

Development

# Install dependencies
npm install

# Build
npm run build

# Type check
npm run typecheck

# Run locally
DATAFAST_API_KEY=df_your_key node dist/index.js

Troubleshooting

"DATAFAST_API_KEY environment variable is required"

Ensure your AI client (Cursor, Claude Desktop, etc.) is configured to pass the DATAFAST_API_KEY in the env object. The key must start with df_.

"Invalid API key format"

DataFast API keys start with df_. Verify you copied the full key from the DataFast dashboard → Settings → API Keys.

MCP server not appearing in Cursor

1. Restart Cursor after adding the MCP config
2. Ensure the config file is at .cursor/mcp.json (or the path your Cursor version expects)
3. Check that npx can resolve @datafast/mcp-server (try running npx -y @datafast/mcp-server in a terminal with DATAFAST_API_KEY set)

API errors

If you see DataFast API error (401), your API key may be invalid or expired. Generate a new key from the dashboard. For DataFast API error (403), check that your API key has the required permissions.

License

MIT