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+):

uv sync

3. Run the server:

uv run main.py

MCP Client Config

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

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

Running Tests

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
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