# @datafast/mcp-server

An [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) server that exposes [DataFast](https://datafa.st) 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](https://datafa.st) account with an API key

## Setup

### 1. Get your API key

Go to your [DataFast dashboard](https://datafa.st/dashboard) → Settings → API Keys and create a new key.

### 2. Install

```bash
npm install @datafast/mcp-server
```

### 3. Configure your AI client

#### Cursor

Add this to your `.cursor/mcp.json`:

```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):

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

```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

```bash
# 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](https://datafa.st/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