Lazy Toggl MCP Server — Toggl API Time Tracking

Overview

Lazy Toggl MCP Server is a lightweight, unofficial Model Context Protocol (MCP) server that forwards simple time-tracking commands to the Toggl API. It provides a compact HTTP interface intended for tooling, chat assistants, or automation scripts that need fast and reliable start/stop/project logging without handling the full Toggl REST surface directly.

By exposing a small set of MCP-style tools (start/stop/status/list projects), the server lets developers and assistants control Toggl time entries with minimal configuration. It is useful when you want a single, dependable bridge between an automation client (or AI agent) and Toggl for consistent, auditable time tracking.

Features

• Minimal MCP-compatible HTTP interface for time tracking workflows
• Start and stop Toggl time entries with a single JSON call
• Project and tag lookup to attach metadata to time entries
• Lightweight deployment: run locally, in a container, or behind a reverse proxy
• Simple environment-based configuration using your Toggl API token
• Fast, idempotent operations suitable for automation and AI toolchains

Installation / Configuration

Clone the repository and choose a deployment method. The repository contains a small server; it can be run from source or packaged as a container.

1. Clone the repository

git clone https://github.com/movstox/lazy-toggl-mcp.git
cd lazy-toggl-mcp

2. Environment variables Set at least your Toggl API token and the server port. Example variables:

• TOGGL_API_TOKEN — your Toggl personal access token
• PORT — port to listen on (default: 8080)
• MCP_SECRET — optional secret to secure MCP calls
• LOG_LEVEL — optional logging verbosity (info, debug)

Example .env file:

TOGGL_API_TOKEN=your_toggl_api_token_here
PORT=8080
MCP_SECRET=some-secret-key
LOG_LEVEL=info

3a) Run with Docker

# Build image (if the repo contains a Dockerfile)
docker build -t lazy-toggl-mcp .

# Run container with env vars
docker run -d \
  -e TOGGL_API_TOKEN=your_toggl_api_token_here \
  -e PORT=8080 \
  -e MCP_SECRET=your_mcp_secret \
  -p 8080:8080 \
  --name lazy-toggl-mcp \
  lazy-toggl-mcp

3b) Run from source (example pattern) If the project provides an NPM or Python start command, run it after installing dependencies. Replace with the appropriate command in the repository.

# Node.js (example)
npm install
export TOGGL_API_TOKEN=your_toggl_api_token_here
npm start

# Python (example)
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
export TOGGL_API_TOKEN=your_toggl_api_token_here
python app.py

Available Tools / Resources

The server exposes a concise set of tools to operate on Toggl data. Typical tool names and inputs:

• time.start
  • Input: description, project_id (optional), tags (optional), billable (optional)
  • Output: time_entry object (id, start, description, project_id)
• time.stop
  • Input: time_entry_id
  • Output: time_entry object (id, stop, duration)
• time.status
  • Input: none
  • Output: running time_entry (if any)
• projects.list
  • Input: workspace_id (optional)
  • Output: list of projects (id, name, client)

Example: Start a timer via curl (replace URL and secret as configured)

curl -X POST http://localhost:8080/mcp/run \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_mcp_secret" \
  -d '{
    "tool": "time.start",
    "input": {
      "description": "Investigate bug #123",
      "project_id": 987654,
      "tags": ["bugfix","urgent"],
      "billable": true
    }
  }'

Expected result (JSON): a started time entry with id and start timestamp.

To stop the current entry:

curl -X POST http://localhost:8080/mcp/run \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_mcp_secret" \
  -d '{
    "tool": "time.stop",
    "input": {
      "time_entry_id": 123456789
    }
  }