# WakaTime MCP Server
A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that provides high-signal coding analytics from your [WakaTime](https://wakatime.com/) data.
- **Direct mode**: FastMCP serves Streamable HTTP at `http://localhost:8000/mcp`
- **Proxy mode**: `mcp-proxy` exposes the server over SSE/HTTP and Caddy adds token auth (recommended for self-hosting)
## Tooling / API
| Tool | Purpose | Key arguments |
|------|---------|---------------|
| `get_coding_stats` | Detailed stats for a period | `range` (`last_7_days`, `last_30_days`, `last_6_months`, `last_year`, `all_time`) |
| `get_summary` | Activity breakdown for a date/range | `start_date`, `end_date`, `project` |
| `get_all_time` | Total coding time since account creation | `project` (optional) |
| `get_status_bar` | Current day status (like editor status bar) | (none) |
| `list_projects` | List/search tracked projects | `query` (optional) |
## Configuration
Configure via environment variables (or a `.env` file for the self-hosted scripts).
| Variable | Description | Required |
|----------|-------------|----------|
| `WAKATIME_API_KEY` | Your API key from https://wakatime.com/settings/api-key | **Yes** |
| `MCP_AUTH_KEY` | Token for auth proxy (proxy/self-hosted mode) | Proxy mode |
| `PORT` | Direct-mode port (default: `8000`) | No |
## Development (Direct mode)
1. **Install (uv required)**
```bash
git clone https://github.com/dpshade/wakatime-mcp.git
cd wakatime-mcp
uv sync --no-install-project
```
2. **Run**
```bash
WAKATIME_API_KEY="your_wakatime_api_key_here" uv run -- python src/server.py
```
3. **Connect**
- **URL**: `http://localhost:8000/mcp`
- **Auth**: none
## Deployment
### Option 1: Self-hosted with auth (recommended)
This mode runs the MCP server with FastMCP’s default **stdio** transport and uses `mcp-proxy` to expose it over HTTP:
```
Internet -> (optional Tailscale Funnel) -> Caddy (auth) -> mcp-proxy -> FastMCP (stdio)
:8770 :8767
```
1. **Configure**
```bash
cp .env.example .env
# Edit .env: set WAKATIME_API_KEY and a strong MCP_AUTH_KEY
```
2. **Download Caddy (auth proxy)**
```bash
curl -L https://github.com/caddyserver/caddy/releases/latest/download/caddy_linux_amd64 -o deploy/caddy
chmod +x deploy/caddy
```
3. **Start**
```bash
./deploy/start.sh
```
4. **Endpoints**
- **Auth proxy (recommended):**
- SSE: `http://localhost:8770/sse`
- Streamable HTTP: `http://localhost:8770/mcp`
- **Internal (no auth; do not expose publicly):**
- SSE: `http://localhost:8767/sse`
- Streamable HTTP: `http://localhost:8767/mcp`
`mcp-proxy` also exposes a health endpoint at `http://localhost:8767/status` (and via auth proxy at `http://localhost:8770/status`).
#### Systemd (persistent)
```bash
./deploy/install-systemd.sh
sudo systemctl enable --now mcp-wakatime mcp-wakatime-auth
```
#### Optional: Tailscale Funnel
If you use Tailscale, you can publish the auth proxy port:
```bash
tailscale funnel --bg --set-path=/wakatime localhost:8770
tailscale funnel --bg 443 on
```
### Option 2: Docker
Runs `mcp-proxy` + the server in a container.
```bash
cd deploy
docker-compose up -d
```
- **Endpoint (no auth):** `http://localhost:8767/sse`
- If you want auth, run Caddy on the host (or add it to your own compose stack) and proxy to `8767`.
### Option 3: Render
This repo includes `render.yaml` for deploying the **direct** Python server.
- Set environment variable: `WAKATIME_API_KEY`
- Your service endpoint will be: `https://<your-service>/mcp`
## Client setup
### MCP Inspector
```bash
npx @modelcontextprotocol/inspector
```
Then connect using:
- Direct mode: `http://localhost:8000/mcp` (Streamable HTTP)
- Proxy mode: `http://localhost:8770/sse` (SSE)
### Poke / other hosted clients (proxy mode)
Use the auth proxy SSE endpoint and send `MCP_AUTH_KEY` via **one** of:
- `Authorization: Bearer <MCP_AUTH_KEY>`
- `X-API-Key: <MCP_AUTH_KEY>`
- `Api-Key: <MCP_AUTH_KEY>`
## Security notes
- Generate a strong auth key:
```bash
openssl rand -hex 32
```
- Never expose the unauthenticated `mcp-proxy` port (`8767`) to the public internet.
## License
MIT
