toggl

Toggl MCP Server provides an MCP interface to interact with the Toggl time tracking API. It lets an AI assistant create, update, delete, and query time entries, fetch current running entries, stop running entries, and retrieve workspace and project information within Toggl. After starting the server (via the Docker command in the MCP config), connect your AI assistant to the server using the configured mcp.json, and you can issue natural-language commands like: create a new time entry for project X, get all time entries for today, or stop the current running entry. The server handles the translation of natural language requests into Toggl API calls and returns structured results that the assistant can present to you.

Capabilities include filtering time entries by date, project, or workspace; retrieving the current running time entry; creating and updating entries with descriptions, durations, and project associations; and listing workspaces and their projects. It is designed for cross-platform use (linux/amd64, linux/arm64) when deployed via Docker.

Prerequisites:

• Docker installed on the host machine
• Access token for Toggl API (TOGGL_API_TOKEN)

Step-by-step:

1. Ensure Docker is running on your machine.

2. Create an MCP configuration file at .cursor/mcp.json with the following content:

{
  "mcpServers": {
    "toggl-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "TOGGL_API_TOKEN",
        "lyricrime/toggl-mcp-server"
      ],
      "env": {
        "TOGGL_API_TOKEN": "your_toggl_api_token"
      }
    }
  }
}

3. Replace your_toggl_api_token with your actual Toggl API token.

4. Run your environment so the MCP server can be connected by your AI assistant. The assistant should now be able to issue natural language commands to Toggl through the MCP interface.

Notes:

• TOGGL_API_TOKEN is required and should be kept secure; avoid committing it to version control.
• The server is provided as a Docker image (lyricrime/toggl-mcp-server) and supports multi-platform Docker runtimes.
• If you rotate your Toggl API token, update the TOGGL_API_TOKEN in your MCP config accordingly.
• The MCP interface expects the host to provide the environment variable in the mcp.json file; ensure the environment is correctly passed to Docker.
• For troubleshooting, verify that Docker can pull the image and that the Toggl token has the necessary permissions (read/write as needed for time entries).