# toggl-mcp

A [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that gives Claude access to your [Toggl Track](https://toggl.com/track/) time tracking data.

Ask Claude things like:
- *"What am I tracking right now?"*
- *"How much time did I spend on each project this week?"*
- *"Start a timer for writing documentation on the Blog project"*
- *"Stop my timer"*
- *"What did I work on yesterday?"*

---

## Tools

| Tool | What it does |
|------|-------------|
| `get_current_timer` | Shows the currently running time entry |
| `get_recent_entries` | Time entries for the past N days (default 7) |
| `get_projects` | Lists all your projects |
| `get_summary` | Total time by project for a date range |
| `start_timer` | Starts a new time entry |
| `stop_timer` | Stops the current timer |
| `get_profile` | Your Toggl profile and workspaces |

---

## Setup

### 1. Get your API token

1. Go to **https://track.toggl.com/profile**
2. Scroll to the bottom
3. Click **"Click to reveal"** under API Token
4. Copy the token

### 2. Install

```bash
npm install -g toggl-mcp
```

Find the installed path:
```bash
which toggl-mcp
```

### 3. Add to Claude Desktop

Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS):

```json
{
  "mcpServers": {
    "toggl": {
      "command": "/path/from/which/toggl-mcp",
      "env": {
        "TOGGL_API_TOKEN": "your_token_here"
      }
    }
  }
}
```

Or if running from source:

```json
{
  "mcpServers": {
    "toggl": {
      "command": "node",
      "args": ["/path/to/toggl-mcp/dist/index.js"],
      "env": {
        "TOGGL_API_TOKEN": "your_token_here"
      }
    }
  }
}
```

Restart Claude Desktop. You should see a green "running" badge in **Settings → Developer**.

### 4. Test it

```
What am I currently tracking in Toggl?
```

---

## Example queries

**Daily check-in:**
```
What have I tracked today in Toggl?
```

**Weekly review:**
```
Give me a summary of how I spent my time this week by project
```

**Start tracking:**
```
Start a Toggl timer for "reviewing PRs" on my Engineering project
```

**Stop and summarize:**
```
Stop my timer and tell me how long I worked
```

**Productivity analysis:**
```
How much time did I track last week vs the week before?
Which project took the most time?
```

---

## Development

```bash
git clone https://github.com/yourusername/toggl-mcp
cd toggl-mcp
npm install
npm run build

# Test locally
TOGGL_API_TOKEN=your_token node dist/index.js
```

### Project structure

```
toggl-mcp/
├── src/
│   ├── index.ts   # MCP server + tool definitions
│   └── toggl.ts   # Toggl API v9 client + formatters
├── package.json
├── tsconfig.json
└── README.md
```

---

## Rate limits

Toggl's free plan allows 30 requests/hour per workspace. This MCP server batches calls where possible (e.g. fetching projects and entries in parallel) to stay well within limits for normal use.

---

## Contributing

PRs welcome. Ideas for extension:
- Tags management
- Client listing
- Detailed reports (daily breakdown)
- Time entry editing

---

## License

MIT

---

## Acknowledgements

Built with the [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk) and the [Toggl Track API v9](https://engineering.toggl.com/docs/track/).