# Deep Work Timer MCP server

Pomodoro and deep work time tracking for AI coding agents, with a permanent per-skill ledger.

This is the [Model Context Protocol](https://modelcontextprotocol.io) server for [Deep Work Timer](https://deepworktimer.com). It lets Claude Code, Claude Desktop, Cursor, Windsurf, or any MCP client start and log focus sessions, manage tasks, and read how many hours you have put into each skill. Every session lands in your ledger at deepworktimer.com: today, this week, a 12-week heatmap, and lifetime hours per `#skill`. Free, no subscription, no session limit.

Typical use: you tell your agent "track this as #python for the next hour". It creates the task, starts a 60 minute session, switches tasks as the work moves, and logs the block when you are done. Six months later you can ask "how many hours have I put into Python?" and get a number.

## Install

You need a free account at [deepworktimer.com](https://deepworktimer.com) and an API token (Settings > API tokens). If you already use the [dwt CLI](https://github.com/stirredo/deepwork-timer-skill), the server reads its token from `~/.deepworktimer/token` and no extra setup is needed.

### Claude Code

```bash
claude mcp add deepworktimer -e DWT_TOKEN=your_token -- npx -y deepworktimer-mcp
```

### Claude Desktop, Cursor, Windsurf and other clients

Add to the client's MCP config:

```json
{
  "mcpServers": {
    "deepworktimer": {
      "command": "npx",
      "args": ["-y", "deepworktimer-mcp"],
      "env": { "DWT_TOKEN": "your_token" }
    }
  }
}
```

## Tools

| Tool | What it does |
|---|---|
| `dwt_status` | Active session (task, time left, which device owns it) and today's total |
| `dwt_stats` | Focus time today / 7d / 30d / 365d / all time, best day, daily average |
| `dwt_lifetime_skills` | The 10,000-hour ledger: lifetime hours per `#skill` with the next milestone |
| `dwt_deposits_today` | Today's completed sessions, itemized |
| `dwt_list_projects`, `dwt_create_project` | Projects group tasks (a repo, a course, a certification) |
| `dwt_list_tasks`, `dwt_create_task`, `dwt_complete_task` | Tasks; `#tags` in the description attach skills, `@1h30m` sets an estimate |
| `dwt_start_session` | Start a server-side session (1 to 240 min; default is your pomodoro length) |
| `dwt_switch_task` | Move the running session to another task; time is split honestly |
| `dwt_log_session` | Complete the running session and write it to the ledger |
| `dwt_abandon_session` | Discard the running session |
| `dwt_log_pomodoro` | Record N minutes on a task after the fact |

Sessions are account-wide: one active session, visible from your phone, laptop and agent. Starting a new one takes over any running session, so the tool descriptions steer agents to `dwt_status` first and `dwt_switch_task` when something is already running. Logging refuses if another device owns the open segment (you might be working there) unless you explicitly ask.

## Configuration

| Variable | Default | Purpose |
|---|---|---|
| `DWT_TOKEN` | `~/.deepworktimer/token` | API token |
| `DWT_BASE_URL` | `https://deepworktimer.com` | Point at a self-hosted instance |
| `DWT_SOURCE` | `mcp:<hostname>` | Device label shown on sessions started here |

## Why a ledger and not a streak

Most timers count down and forget. Deep Work Timer keeps the count: hours per day, per week, per skill, for as long as you keep the account. There is no premium tier and nothing is deleted when you stop paying, because there is nothing to pay. The number only goes up.

## Development

```bash
npm install
npm test        # builds, then runs node:test against dist/
node dist/index.js   # stdio server; talk to it with an MCP inspector
```

The REST API this wraps is the same one the web app and the `dwt` CLI use. Two API quirks are handled for you: `POST /api/tasks` does not attach `#skills` (a follow-up `PATCH` does), and estimates are patched separately in minutes.

## License

MIT