toggl-mcp

MCP server that fills Toggl Track from your Claude Code sessions: work time from session activity, descriptions from session titles, preview before writing.

Claude Code session transcripts already record when you worked on a task and what the session was about. preview_timesheet turns that into proposed time entries for a date range, cut around anything already in Toggl. create_time_entries writes them once you confirm. Runs locally over stdio; the API token is only sent to Toggl.

How time is counted

1. Activity comes from the Claude Code transcripts of each configured repo (~/.claude/projects/<repo path with non-alphanumerics replaced by ->*/*.jsonl): every prompt, reply and tool call has a timestamp, the git branch and the working directory. Subagent activity counts too.

2. One session becomes one or more entries: a pause longer than idleGapMin ends an entry, and each entry gets tailMin extra minutes for reading the last answer. Entries shorter than minEntryMin are dropped.

3. Description: the session title in effect when the entry ended — the one you set with /rename, otherwise the title Claude Code generates (the one in /resume). Sessions without a title use their first prompt.

4. No minute is counted twice: proposed entries are cut around existing Toggl entries (in any project) and around each other when sessions run in parallel. Running the preview again after writing proposes nothing new.

Related MCP server: Toggl MCP Server

Setup

Requires Node 22+.

npm install
npm run build

Get the API token in Toggl Track → Profile settings → API Token, then register the server for all your Claude Code projects:

claude mcp add toggl --scope user -e TOGGL_API_TOKEN=<token> -- node /absolute/path/to/toggl-mcp/dist/index.js

Create the config (default ~/.config/toggl-mcp/config.json, or point TOGGL_MCP_CONFIG at another file):

mkdir -p ~/.config/toggl-mcp
cp config.example.json ~/.config/toggl-mcp/config.json

Ask Claude to run toggl_status: it checks the token and lists workspace and project ids for the config.

Config

{
  "workspaceId": 1234567,
  "timezone": "Europe/London",
  "idleGapMin": 20,
  "tailMin": 5,
  "minEntryMin": 5,
  "repos": [
    { "path": "~/projects/my-app", "projectId": 7654321, "tags": ["claude"] }
  ]
}

The config is read on every call, so edits apply without restarting.

Tools

Typical use in Claude Code:

Fill Toggl for yesterday

Claude calls preview_timesheet, shows the table, and writes after you confirm — or with your edits ("drop #3, make #2 end at 18:30").

Plans live in memory until the server restarts.

Limits

• Only time spent with Claude Code is visible. Work outside it (meetings, manual coding) is not tracked.

• Activity is attributed by the working directory of the session: a session started in one repo counts for that repo, whatever it works on.

• A long session that covers several tasks is described by its title at the time; rename the session (/rename) when you switch tasks to get accurate descriptions.

• Toggl returns time entries for roughly the last three months.

Development

npm run dev        # tsc --watch
npm test           # node:test on src/ via type stripping
npx @modelcontextprotocol/inspector node dist/index.js

License

MIT