toggl-mcp-server

toggl-mcp-server

3
developer_toolsos_automation

The Toggl MCP Server enables interaction with Toggl Track using natural language through MCP clients. It supports time tracking and project management, making it easier to manage workspaces and integrate with development tools like VS Code and GitHub Copilot.

Toggl MCP Server

Allows MCP clients to interact with Toggl Track, enabling time tracking, project management, and workspace operations through natural language.

Features

Tools

Project Management

  • create_project

    • Description: Creates a new project in a specified Toggl workspace.
    • Input:
      • name (str): The name of the project to be created. This is a required field.
      • workspace_name (str, optional): The name of the workspace where the project will be created. If not provided, it defaults to the user's default workspace.
      • active (bool, optional): Specifies whether the project is active. Defaults to True.
      • billable (bool, optional): Specifies whether the project is billable. Defaults to False.
      • client_id (int, optional): The ID of the client associated with the project.
      • color (str, optional): The hex color code assigned to the project (e.g., "#FF0000").
      • is_private (bool, optional): Specifies whether the project is private. Defaults to True.
      • start_date (str, optional): The start date of the project in ISO 8601 format (e.g., "YYYY-MM-DD").
      • end_date (str, optional): The end date of the project in ISO 8601 format (e.g., "YYYY-MM-DD").
      • estimated_hours (int, optional): The estimated number of hours for the project.
      • template (bool, optional): Specifies whether the project is a template. Defaults to False.
      • template_id (int, optional): The ID of the template to use for creating the project.
    • Output: JSON response containing the data of the newly created project.

  • delete_project

    • Description: Deletes a project identified by its name within a specified workspace.
    • Input:
      • project_name (str): The exact name of the project to be deleted. This is a required field.
      • workspace_name (str, optional): The name of the workspace containing the project. If not provided, it defaults to the user's default workspace.
    • Output: A confirmation message (str) indicating the successful deletion of the project.

  • update_projects

    • Description: Performs bulk updates on multiple projects within a specified workspace using patch operations.
    • Input:
      • project_names (List[str]): A list containing the names of the projects to be updated. This is a required field.
      • operations (List[dict]): A list of patch operations to apply to the selected projects. Each operation is a dictionary specifying the operation type (op), the field path (path), and the new value (value) (e.g., {"op": "replace", "path": "/active", "value": false}). This is a required field.
      • workspace_name (str, optional): The name of the workspace containing the projects. If not provided, it defaults to the user's default workspace.
    • Output: JSON response containing the data of the updated projects.

  • get_all_projects

    • Description: Retrieves a list of all projects within a specified workspace.
    • Input:
      • workspace_name (str, optional): The name of the workspace from which to retrieve projects. If not provided, it defaults to the user's default workspace.
    • Output: JSON response containing a list of project data objects found in the specified workspace.
Time Entry Management

  • new_time_entry

    • Description: Creates a new time entry. Can be used to start a timer (if only start is provided or neither start nor duration are provided) or log a completed time entry (if start and stop, or start and duration are provided).
    • Input:
      • description (str): The description for the time entry.
      • workspace_name (str, optional): Name of the workspace. Defaults to the user's default workspace.
      • project_name (str, optional): Name of the project to associate the time entry with.
      • tags (List[str], optional): A list of tag names to apply to the time entry.
      • start (str, optional): The start time of the entry in ISO 8601 format (e.g., "2023-10-26T10:00:00Z"). Defaults to the current time if creating a running entry.
      • stop (str, optional): The stop time of the entry in ISO 8601 format. If provided, creates a completed entry.
      • duration (int, optional): The duration of the entry in seconds. If start is provided but stop is not, duration determines the stop time. If start is not provided, a negative duration starts a running timer.
      • billable (bool, optional): Whether the time entry should be marked as billable. Defaults to False.
      • created_with (str, optional): The name of the application creating the entry. Defaults to "MCP".
    • Output: JSON response containing the data of the created time entry.

  • stop_time_entry

    • Description: Stops the currently running time entry.
    • Input:
      • workspace_name (str, optional): Name of the workspace where the entry is running. Defaults to the user's default workspace.
    • Output: JSON response containing the data of the stopped time entry.

  • delete_time_entry

    • Description: Deletes a specific time entry by its description and start time.
    • Input:
      • time_entry_description (str): The exact description of the time entry to delete.
      • start_time (str): The exact start time of the entry in ISO 8601 format used for identification.
      • workspace_name (str, optional): Name of the workspace containing the entry. Defaults to the user's default workspace.
    • Output: Success confirmation message (str) upon successful deletion.

  • get_current_time_entry

    • Description: Fetches the details of the currently running time entry.
    • Input: None (implicitly uses the user's context).
    • Output: JSON response containing the data of the currently running time entry, or None if no time entry is currently running.

  • update_time_entry

    • Description: Updates attributes of an existing time entry identified by its description and start time.
    • Input:
      • time_entry_description (str): The current description of the time entry to update.
      • start_time (str): The exact start time of the entry in ISO 8601 format used for identification.
      • workspace_name (str, optional): Name of the workspace containing the entry. Defaults to the user's default workspace.
      • new_description (str, optional): New description for the time entry.
      • project_name (str, optional): New project name to associate with the entry. Set to empty string "" to remove project association.
      • tags (List[str], optional): A new list of tag names. This will replace all existing tags. Provide an empty list [] to remove all tags.
      • new_start (str, optional): New start time in ISO 8601 format.
      • new_stop (str, optional): New stop time in ISO 8601 format.
      • billable (bool, optional): New billable status.
    • Output: JSON response containing the data of the updated time entry.

  • get_time_entries_for_range

    • Description: Retrieves time entries within a specified date range, defined by offsets from the current day.
    • Input:
      • from_day_offset (int): The start day offset from today (e.g., 0 for today, -1 for yesterday, -7 for a week ago).
      • to_day_offset (int): The end day offset from today (e.g., 0 for today, 1 for tomorrow). The range includes both the start and end dates.
      • workspace_name (str, optional): Name of the workspace to fetch entries from. Defaults to the user's default workspace.
    • Output: JSON response containing a list of time entries found within the specified date range.

Getting Started

Prerequisites

  • Python 3.11+
  • Toggl Track account
  • uv installed for dependency management

Environment Variables

Create a .env file inside of the mcp_toggl_server folder with:

EMAIL=your_toggl_email
PASSWORD=your_toggl_password

Installation

First install uv: - For MacOS/Linux: bash curl -LsSf https://astral.sh/uv/install.sh | sh - For Windows: bash powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Make sure to restart your terminal afterwards to ensure that the uv command gets picked up.

Now let's clone the repository and set up the project:

git clone [repository-url]
cd mcp_toggl_server
uv venv
uv pip install --all

Integration with Development Tools

VS Code + GitHub Copilot Setup
  1. Configure the MCP Server in .vscode/mcp.json:
"servers": {
  "toggl": {
    "type": "stdio",
    "command": "uv",
    "args": [
      "--directory",
      "/ABSOLUTE/PATH/TO/PARENT/FOLDER/mcp_toggl_server",
      "run",
      "toggl_mcp_server.py"],
    "envFile": "${workspaceFolder}/mcp_toggl_server/.env"
  }
}

  1. Update the configuration:

    • Replace /ABSOLUTE/PATH/TO/PARENT/FOLDER/mcp_toggl_server with the absolute path to the server
    • You may need to put the full path to the uv executable in the command field. You can get this by running which uv on MacOS/Linux or where uv on Windows

  2. Enable the server:

    • Look for the start button when hovering over the server configuration /.vscode/mcp.json
    • Click start to let Copilot discover available tools
    • Switch to agent mode in Copilot

For detailed setup instructions, see:

Additional MCP Client Integration

The Toggl MCP Server works with any MCP-compatible client. For integration steps:

  1. For Claude Desktop, visit the MCP Quick Start Guide
  2. For other MCP clients, consult their respective documentation for server configuration

Note: Configuration typically involves specifying the server path and environment variables similar to the VS Code setup above.

Testing with MCP Inspector

To run in development:

EMAIL=your_toggl_email PASSWORD=your_toggl_password mcp dev toggl_mcp_server.py

License

This MCP server is licensed under the MIT License.