Lazy Toggl MCP

What is Lazy Toggl MCP Server?

Lazy Toggl MCP Server is an unofficial Model Context Protocol (MCP) server designed to integrate with the Toggl Track API. It allows users to track their time directly through an MCP server, providing a simplified way to manage time entries.

How to use Lazy Toggl MCP Server?

To use Lazy Toggl MCP Server, you need to:

1. Clone the repository and install dependencies using uv sync.
2. Obtain your Toggl API Token from your Toggl Track account settings.
3. Configure the MCP server by adding the provided JSON configuration to your MCP settings file. Remember to replace the placeholder path with the actual path to the project and your-actual-api-token-here with your Toggl API token.

Once configured, you can use the provided tools to interact with Toggl time tracking.

Key Features of Lazy Toggl MCP Server

• Time Tracking Management: Start and stop time entries for various tasks.
• Current Entry Retrieval: Easily view the currently running time entry.
• Workspace Listing: List all available Toggl workspaces.
• API Tools: Provides specific tools for start_tracking, stop_tracking, list_workspaces, and show_current_time_entry.
• Toggl Track API Integration: Utilizes key Toggl Track API v9 endpoints for seamless interaction.

Use Cases of Lazy Toggl MCP Server

• Automated Time Tracking: Integrate time tracking into automated workflows or scripts.
• Custom Applications: Build custom applications or interfaces that require Toggl time tracking functionality.
• Developer Tools: Provide a convenient way for developers to manage their time entries without directly interacting with the Toggl web interface.

FAQ about Lazy Toggl MCP Server

Q: What is an MCP server? A: An MCP (Model Context Protocol) server provides tools and functionalities that can be integrated into various applications or systems, allowing for standardized communication and interaction.

Q: Do I need a Toggl Track account to use this? A: Yes, you need an active Toggl Track account and an API token to use this server, as it interacts directly with the Toggl Track API.

Q: Can I modify the project? A: Yes, the project is released under the MIT License, allowing you to modify and use it as needed.

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.