# xeve-mcp-server

MCP server for [xeve](https://xeve.io) — query your personal analytics from any AI assistant (Claude Desktop, Claude Code, etc.)

Ask questions like:
- "How much did I code today?"
- "What's my productivity trend this week?"
- "What music was I listening to yesterday?"
- "Does my sleep correlate with coding output?"

## Setup

### 1. Get your access token

Go to [xeve.io/dashboard/settings](https://xeve.io/dashboard/settings) → **API Access** and copy your access token.

### 2. Configure Claude Desktop

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

```json
{
  "mcpServers": {
    "xeve": {
      "command": "npx",
      "args": ["-y", "xeve-mcp-server"],
      "env": {
        "XEVE_ACCESS_TOKEN": "your-access-token-here"
      }
    }
  }
}
```

### 3. Configure Claude Code

```bash
claude mcp add xeve -e XEVE_ACCESS_TOKEN=your-access-token-here -- npx -y xeve-mcp-server
```

## Tools

| Tool | Description |
|------|-------------|
| `get_productivity_summary` | Screen time, productive time, distracted time, top categories |
| `get_app_usage` | Which apps you used and for how long |
| `get_coding_summary` | Coding time by project and language |
| `get_health_summary` | Steps, energy, sleep, heart rate from HealthKit |
| `get_music_history` | Spotify listening history, top artists, recent tracks |
| `get_github_activity` | Commits, PRs, reviews, lines changed, active repos |
| `get_correlations` | Statistical correlation between any two metrics |
| `get_daily_trend` | Day-by-day breakdown of all metrics |
| `get_recent_sessions` | Most recent app sessions with window titles |

All tools accept optional `from` and `to` parameters (YYYY-MM-DD) to filter by date range. Defaults to today.

## Examples

**"How productive was I this week?"**
→ Calls `get_productivity_summary` with this week's date range

**"What projects did I code on yesterday?"**
→ Calls `get_coding_summary` with yesterday's date

**"Does sleep affect my coding output?"**
→ Calls `get_correlations` with `metric_a: "sleep_ms"`, `metric_b: "coding_ms"`

**"Show me my daily trend for March"**
→ Calls `get_daily_trend` with `from: "2026-03-01"`, `to: "2026-03-31"`

## Available correlation metrics

`total_tracked_ms`, `productive_ms`, `distracted_ms`, `communication_ms`, `app_switches`, `coding_ms`, `listening_ms`, `tracks_played`, `recovery_score`, `strain`, `hrv`, `sleep_ms`, `step_count`, `active_energy_kcal`, `commits`, `prs_opened`, `prs_merged`, `avg_heart_rate`

## Development

```bash
git clone https://github.com/xeveio/xeve-mcp-server.git
cd xeve-mcp-server
npm install
npm run build
XEVE_ACCESS_TOKEN=your-token node dist/index.js
```

## License

MIT