Skip to main content
Glama
toggl-track-mcp-server

toggl-track-mcp-server

by Hiroto0706

toggl-track-mcp-server

TypeScript MCP server (stdio) exposing tools to fetch Toggl Track v9 time entries.

Features

  • Single‑day time entry fetch using Toggl v9 (/api/v9/me/time_entries).

  • Timezone aware via Temporal polyfill (@js-temporal/polyfill):

    • Accepts any IANA timezone (e.g. Asia/Tokyo, America/New_York).

    • If timezone is omitted, uses your Toggl account timezone (fetched via /api/v9/me), with fallback to UTC.

Directory Layout

  • src/index.ts – MCP server bootstrap (registers tools)

  • src/tools/ – Tool implementations

    • ping.ts

    • get_time_entries_for_date.ts

    • check_auth.ts

  • src/toggl/ – Toggl API client

    • get.ts (fetchTimeEntriesForDateV9, fetchMe)

  • src/utils/ – Utilities

    • config.ts (env loader)

    • date.ts (Temporal‑based dayRange)

  • src/schemas/ – Zod and shared types

    • date.ts, toggl.ts, tools.ts

Environment

  1. Copy .env.template to .env and set values:

cp .env.template .env

Required

  • TOGGL_API_TOKEN

Notes

  • .env is auto‑loaded via dotenv/config.

  • You can also pass the token via MCP client env.

Build

npm i
npm run build

Run (stdio)

node dist/index.js --transport stdio

Use with Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "toggl-track": {
      "command": "/opt/homebrew/bin/node",
      "args": [
        "--enable-source-maps",
        "/Users/yourname/path/to/toggl-track-mcp-server/dist/index.js",
        "--transport",
        "stdio"
      ],
      "env": {
        "TOGGL_API_TOKEN": "YOUR_TOKEN",
        "TZ": "Asia/Tokyo"
      }
    }
  }
}

Use with MCP Inspector

npx @modelcontextprotocol/inspector
  • Add Server → Stdio

    • Command: node (or absolute node path)

    • Args: /path/to/dist/index.js --transport stdio

    • Env: TOGGL_API_TOKEN=..., TZ=Asia/Tokyo

Tools

  • ping

    • Returns ok.

  • check_auth

    • Verifies token via /api/v9/me and returns a masked summary.

    • Params: none (uses TOGGL_API_TOKEN from env).

  • get_time_entries_for_date

    • Fetches v9 time entries for a single date.

    • Params (JSON):

      • date (string, optional; accepts YYYY-MM-DD, YYYY/MM/DD, 今日, 昨日, 一昨日; omitted means today)

      • timezone (string, IANA; optional → uses account timezone; fallback UTC)

      • apiToken (string; optional override for env)

    • Returns (JSON):

      • { meta: { source: 'v9', date, timezone, startUTC, endUTC, count }, entries: [...] }

Notes

  • This project uses Node ESM with module: nodenext. Write relative imports with .js extensions in source.

  • Timezone math uses Temporal via @js-temporal/polyfill.

Available Tools

3 tools
check_authA
Read-onlyIdempotent

Verify Toggl API token by calling /api/v9/me.

Inputs: apiToken.

get_time_entries_for_dateA
Read-onlyIdempotent

Fetch Toggl Track v9 time entries for a single date. Timezone accepts any IANA value and defaults to your account timezone (fallback UTC).

Inputs: date, apiToken, timezone.

pingA
Read-onlyIdempotent

Health check tool. Returns "ok".

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 3 tools

    Disambiguation5/5

    The three tools are clearly distinct: ping for health, check_auth for token verification, and get_time_entries_for_date for fetching time entries. There is no overlap or ambiguity between them.

    Naming Consistency4/5

    Tool names mostly follow a clear snake_case pattern with verb-like prefixes. 'ping' deviates slightly from the get_/check_ convention, but all names are lowercase with underscores, making them predictable and readable.

    Tool Count4/5

    With three tools, the server is compact and each tool serves a distinct purpose: health check, auth validation, and data retrieval. While minimal, the count is reasonable for a narrow integration, though it might feel slightly thin for broader Toggl Track functionality.

    Completeness2/5

    The server focuses solely on fetching time entries for a single date, lacking essential operations like creating, updating, or deleting time entries, or retrieving projects/workspaces. This makes the surface significantly incomplete for a full Toggl Track workflow.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Enables timezone conversion, astronomical calculations, and date utilities through natural language, supporting sunrise/sunset, moon phases, business days, and more.
      9
      13 npm
      1
      ISC
    • A
      license
      A
      quality
      D
      maintenance
      Enables AI assistants to manage Toggl Track time entries, projects, and workspaces through natural language, supporting CRUD operations and past date time slots.
      13
      18 npm
      2
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Provides timezone information via timeapi.io, enabling listing of 590+ IANA timezone strings.
      286 npm
      MIT