What is Lazy Toggl Mcp

lazy-toggl-mcp is a Model Context Protocol (MCP) server designed for seamless integration with Toggl, a popular time tracking tool. It provides functionalities for starting and stopping time tracking, retrieving current time entries, and listing workspaces.

Use cases

Use cases for lazy-toggl-mcp include tracking time spent on specific projects, managing multiple workspaces for different clients, and providing insights into time allocation for better decision-making in business operations.

How to use

To use lazy-toggl-mcp, first clone the project and install the dependencies using ‘uv sync’. Configure the server by obtaining your Toggl API token from your Toggl account and adding it to the server configuration. You can then utilize the API to start or stop time tracking and manage your workspaces.

Key features

Key features of lazy-toggl-mcp include starting and stopping time tracking for tasks, retrieving the current time entry, and listing available workspaces. It interacts with the Toggl Track API to provide these functionalities.

Where to use

lazy-toggl-mcp can be used in various fields where time tracking is essential, such as project management, freelance work, and team collaboration. It is particularly useful for individuals and teams looking to optimize their productivity through effective time management.

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.