toggl-mcp

toggl-mcp

A Model Context Protocol (MCP) server that gives Claude access to your Toggl 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

npm install -g toggl-mcp

Find the installed path:

which toggl-mcp

3. Add to Claude Desktop

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

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

Or if running from source:

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

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 and the Toggl Track API v9.