Lazy Toggl MCP Server

Lazy Toggl MCP Server

What is Lazy Toggl MCP Server about?

A lightweight MCP server that lets you interact with the Toggl Track API, enabling start/stop of timers, fetching the current entry, and listing workspaces directly from an MCP client.

How to use Lazy Toggl MCP Server?

1. Install dependencies – clone the repo and run uv sync.
2. Configure the API token – set the TOGGL_API_TOKEN environment variable in the MCP server configuration.
3. Add the MCP server definition to your MCP settings (see the serverConfig field below).
4. Call the provided tools (start_tracking, stop_tracking, show_current_time_entry, list_workspaces) from any MCP‑compatible client.

Key features

• start_tracking – begin a new Toggl time entry with optional title, workspace, project, and tags.
• stop_tracking – stop the currently running entry and receive a confirmation.
• show_current_time_entry – retrieve details of the active entry or a message if none is running.
• list_workspaces – obtain a list of all workspaces associated with the Toggl account.
• Direct mapping to Toggl Track API v9 endpoints.

Use cases

• Automating time‑tracking from scripts or custom IDE extensions.
• Integrating Toggl data into larger workflow‑automation pipelines.
• Building bots that log work automatically based on context.
• Providing a unified interface for multiple developers to manage their Toggl entries without exposing the API token.

FAQ

Q: Do I need a Toggl account? A: Yes, a valid Toggl Track account and its API token are required.

Q: Can I specify a workspace or project when starting tracking? A: Both are optional; if omitted the default workspace/project is used.

Q: How is the server started? A: Through the MCP configuration – the server runs as a stdio process launched by the uv command.

Q: What language is the server written in? A: Python, using the uv tool for dependency management.

Q: Is there any authentication besides the API token? A: No additional authentication is needed; the token is passed via the TOGGL_API_TOKEN environment variable.

Lazy Toggl MCP Server

A Model Context Protocol (MCP) server that provides tools for interacting with Toggl time tracking.

Features

• Start/stop time tracking
• Get current entry
• List workspaces

API

Tools

• start_tracking

  • Start tracking time for a new task
  • Inputs:
    • title (string): Title/description of the task to track
    • workspace_id (integer): Workspace ID (optional, uses default if not provided)
    • project_id (integer): Project ID (optional)
    • tags (string[]): List of tags (optional)

• stop_tracking

  • Stop the currently running time entry
  • No input required
  • Returns confirmation of stopped time entry

• list_workspaces

  • List all available workspaces
  • No input required
  • Returns list of workspaces with their IDs and names

• show_current_time_entry

  • Show the currently running time entry, if any
  • No input required
  • Returns:
    • If tracking: Task description, entry ID, workspace, start time, running duration, tags, and project (if any)
    • If not tracking: A message indicating no time entry is currently running

Integration with Toggl Track API

This server uses the Toggl Track API v9. The following endpoints are utilized:

• GET /me - Get user information
• GET /workspaces - List workspaces
• GET /me/time_entries/current - Get current running time entry
• POST /workspaces/{workspace_id}/time_entries - Start time tracking
• PATCH /workspaces/{workspace_id}/time_entries/{time_entry_id}/stop - Stop time tracking

Installation

1. Clone/create this project
2. Install dependencies with uv:

   cd lazy-toggl-mcp
   uv sync
   

Configuration

Get Your Toggl API Token

1. Go to Toggl Track
2. Sign in to your account
3. Click on your profile picture/avatar in the top right corner
4. Go to "Profile" or "Settings"
5. Find your "API Token" - copy this long string of characters

Configure MCP Server

Add the following configuration to your MCP settings file:

{
  "mcpServers": {
    "lazy-toggl-mcp": {
      "autoApprove": [],
      "disabled": false,
      "timeout": 60,
      "type": "stdio",
      "transportType": "stdio",
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/lazy-toggl-mcp",
        "python",
        "server.py"
      ],
      "env": {
        "TOGGL_API_TOKEN": "your-actual-api-token-here"
      }
    }
  }
}

Important: Replace /path/to/lazy-toggl-mcp with the actual path to this project and your-actual-api-token-here with your real Toggl API token.

Project Structure

lazy-toggl-mcp/
├── src/
│   └── toggl_server/
│       ├── __init__.py      # Package initialization
│       ├── main.py          # MCP server implementation (new structure)
│       ├── models.py        # Data models and type definitions
│       ├── toggl_api.py     # Toggl API client
│       └── utils.py         # Utility functions
├── main.py                  # CLI interface for testing
├── server.py                # Main MCP server entry point
├── pyproject.toml           # Project configuration and dependencies
├── README.md                # This file
├── uv.lock                  # Dependency lock file
├── .gitignore               # Git ignore patterns
└── .python-version          # Python version specification

License

MIT License - feel free to modify and use as needed.