# Toggl MCP

An MCP (Model Context Protocol) server that lets AI assistants log time entries to Toggl Track.

## What it does

Exposes three tools to MCP clients (e.g. Claude):

- **`get_tags`** — lists existing Toggl tags (cached daily)
- **`get_entry_descriptions`** — lists existing time entry descriptions (cached daily)
- **`create_time_entry`** — logs a new time entry with a start time, end time, description, and tag

Also exposes `toggl://tags`, `toggl://entries`, and `toggl://now` as MCP resources.

Time input is in Eastern Time (America/New_York) and converted to UTC before submission.

## Setup

1. Copy `.env.example` to `.env` and fill in your values:

```
BASEURL=https://api.track.toggl.com/api/v9/
CACHE_FOLDER=cache
TOGGL_APIKEY=<your api key>
WORKSPACE_ID=<your workspace id>
```

To find your workspace ID, call the `/me` endpoint with your API key.

2. Install dependencies (requires Python 3.10+):

```bash
uv sync
```

3. Run the server:

```bash
uv run main.py
```

## MCP Client Config

To use with Claude Desktop, add to your MCP config:

```json
{
  "mcpServers": {
    "toggl": {
      "command": "uv",
      "args": ["run", "/path/to/toggl/main.py"]
    }
  }
}
```

## Running Tests

```bash
uv run pytest
```

Tests live in the `tests/` directory. The dev dependency group includes pytest.

## Where to get Toggl API Key

1. Log in to [Toggl Track](https://track.toggl.com)
2. Go to **Profile Settings** (click your avatar in the bottom-left)
3. Scroll to the bottom — your API token is listed under **API Token**
4. Click **Click to reveal** and copy the token