toggl

This Toggl MCP Server exposes a set of tools that let MCP clients interact with Toggl Track directly from natural language commands. Core capabilities include project management (creating, deleting, updating, and listing projects) and time entry management (creating new time entries, stopping running entries, updating entries, deleting entries, and querying time entries by range). The server translates high-level requests into Toggl API actions and returns structured JSON responses with the results. Use cases include creating a new project in a specific workspace, starting and logging time against a project, bulk-updating multiple projects, and retrieving time entries over a date range for reporting. All interactions are authenticated via the environment credentials you provide (EMAIL and PASSWORD) and depend on Toggl Track access associated with that account.

Prerequisites:

• Python 3.11+
• Toggl Track account with API access
• uv (dependency management tool) installed

Installation steps:

1. Prepare your environment

• Ensure Python 3.11+ is installed
• Install uv (example using pipx): bash pipx install uv

2. Obtain the MCP server package

• Clone or download the Toggl MCP server repository (this package corresponds to abhinav24jha-toggl-mcp-server)

3. Run the MCP server via uvx

• Use the uvx command to fetch or run the server package: uvx abhinav24jha-toggl-mcp-server
• Set required environment variables (see below) before starting

4. Validate the server is running

• Confirm the server exposes its MCP interface (check logs for a running status and the port/endpoint).

Notes:\n- If you already have a Python environment, you can activate it and install dependencies as described by the project’s setup instructions.

• The README implies using uv for dependency management; ensure uv is installed and available in your PATH before attempting to run the server.

Environment variables are required to authenticate with Toggl Track. Create a .env file inside the mcp_toggl_server directory or set the variables in your shell before starting:

• EMAIL: Your Toggl Track account email
• PASSWORD: Your Toggl Track password or API token (if you use token-based authentication)

Common issues:

• If you encounter authentication errors, double-check that the credentials are correct and that the Toggl account has API access.
• Ensure the workspace names and project names you reference in requests exist in Toggl; the MCP server will return errors if invalid identifiers are provided.
• When updating time entries, use the exact time formats described (ISO 8601) to avoid parsing errors.

Configuration tips:

• You can customize defaults like workspace_name or default active/billable settings through the API inputs when calling the methods.
• The mcp_config supports environment variables; keep sensitive credentials secure and avoid committing them to version control.