Log your hours from Claude Code
You spent the day in Claude Code on a client's repo and never started a timer. You don't have to rebuild it from memory: Claude Code knows when you were working. With Freelance Tracker's MCP server, “log my hours so far today” is all it takes, and you check every entry before it's written.
Where you'll end up
At any point in the day, one sentence turns your Claude Code sessions into Toggl entries:
Log my hours so far today using FreelanceTracker
You've had two working blocks today, both in acme-storefront: 9:10am–11:40am and 1:40pm–3:10pm. I'll log them to Acme Corp. Here's the first:
freelance-tracker · log_time (preview)
Nothing has been written yet.
Log it?
yes
freelance-tracker · log_time (confirm)
Logged. Second entry: Tue Oct 20 1:40pm–3:10pm (1.50h), “cart tests and PR review”. Log it?
The 💰 total in your menu bar updates as soon as each entry lands. You don't need to press Refresh.
01 Turn on agent access
Open the dashboard, click the ⋯ menu, then Settings → Integrations → Agents (MCP), and tick two boxes:
- Enable MCP server. This lets agents read your hours, pacing and projection. Reads come from the app's cache and never call Toggl.
- Allow agents to log and edit time. This is the switch for this guide. It's off by default.
Leave Anonymize client names off. With it on, writes are refused: an agent that only sees “Project A” shouldn't be logging billable hours.
02 Register the server with Claude Code
Run this once. User scope makes the server available in every project, so you can log time from whichever repo you're in.
claude mcp add --scope user freelance-tracker -- \
~/.freelance-tracker/venv/bin/python \
~/.freelance-tracker/mcp_server.py
Check that it connected with claude mcp list. The Settings pane also has a Test server button and a copy button with your real paths filled in, if you installed somewhere else.
03 Ask
Send this prompt. This is all you really need in practice.
Log my hours so far today using FreelanceTracker
That's it.
Add detail only when you need it:
- “…to Acme Corp” when the repo doesn't say which client it's for.
- “…rounded to quarter hours”, or whatever increment you bill in.
- “log yesterday's hours” works too, for the day you forgot.
04 Read the preview, then say yes
Before anything reaches Toggl, the agent shows you each entry: the date, the time range, the hours, the client and a short note. If you already logged some of that time yourself, it points out the overlap so you don't bill it twice.
Say yes and the entry is logged. Say no, or ask for a change, and nothing is written.
Two blocks mean two confirmations. Every write covers exactly one entry, so you see each one before it lands, and an agent can't log a week in one go.
What the agent can and can't do
Can
- Log a time entry
- Edit or delete an entry
- Read your hours and forecast
Can't
- Write anything without your yes
- Accidentally bulk update or bulk delete
- Change projects, rates or settings
Each entry you confirm costs one Toggl API call and is recorded in ~/Library/Logs/toggl-api-audit.log. Previews are free.
Logged something wrong? Ask the agent to fix it: “that last entry should have been 2 hours” or “delete the duplicate from Tuesday”. Edits and deletes are previewed and confirmed the same way.
If something goes wrong
- “Write access is off”
- Tick Allow agents to log and edit time in Settings → Integrations → Agents (MCP), and Save.
- “Unknown project”
- The name has to match a Toggl project. The error lists the ones it knows, so the agent can usually correct itself.
- “That confirmation is unknown or has expired”
- More than 10 minutes passed, or the token was already used. Ask the agent to preview the entry again.
- The times are off by hours
- The agent skipped the UTC conversion. Tell it your time zone and ask it to redo the preview.