Provides tools to fetch Toggl Track time entries for a given date, with timezone support and authentication verification.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@toggl-track-mcp-server show my time entries for today"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
TypeScript MCP server (stdio) exposing tools to fetch Toggl Track v9 time entries.
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.
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
Copy .env.template to .env and set values:
cp .env.template .envRequired
TOGGL_API_TOKEN
Notes
.env is auto‑loaded via dotenv/config.
You can also pass the token via MCP client env.
npm i
npm run buildnode dist/index.js --transport stdioAdd 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"
}
}
}
}npx @modelcontextprotocol/inspectorAdd Server → Stdio
Command: node (or absolute node path)
Args: /path/to/dist/index.js --transport stdio
Env: TOGGL_API_TOKEN=..., TZ=Asia/Tokyo
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: [...] }
This project uses Node ESM with module: nodenext. Write relative imports with .js extensions in source.
Timezone math uses Temporal via @js-temporal/polyfill.
Verify Toggl API token by calling /api/v9/me.
| Name | Required | Description | Default |
|---|---|---|---|
| apiToken | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds the specific endpoint and verification behavior, which is useful context but does not explain response details or failure handling. With annotations providing the safety baseline, a score of 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is front-loaded and wastes no words. Every part contributes essential information about the tool's purpose and method.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, no output schema, annotations covering safety), the description is complete enough for an agent to understand the tool's function and invoke it correctly. It could add what the response indicates, but the low complexity makes this non-critical.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has one parameter 'apiToken' with 0% description coverage. The description explicitly mentions 'Toggl API token' and the tool name 'check_auth', making it clear that `apiToken` is the token to verify. This compensates for the lack of schema description, though it does not detail token format or acquisition.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Verify' and resource 'Toggl API token' plus the exact endpoint '/api/v9/me', making it clear what the tool does and distinguishing it from sibling tools like 'ping' (likely connectivity) and 'get_time_entries_for_date' (data retrieval).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies the tool is used to verify a Toggl API token by calling the /api/v9/me endpoint. It does not explicitly mention alternatives or exclusions, but the context is sufficiently clear for an agent to choose this tool over siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch Toggl Track v9 time entries for a single date. Timezone accepts any IANA value and defaults to your account timezone (fallback UTC).
| Name | Required | Description | Default |
|---|---|---|---|
| date | No | Target date. Accepts YYYY-MM-DD, YYYY/MM/DD, 今日, 昨日, 一昨日. If omitted, uses today in the resolved timezone. | |
| apiToken | No | Override TOGGL_API_TOKEN from env (useful for testing). | |
| timezone | No | IANA timezone, e.g. 'Asia/Tokyo'. If omitted, uses account timezone; fallback 'UTC'. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description adds meaningful behavioral context: timezone accepts any IANA value, defaults to account timezone, and falls back to UTC. This goes beyond the annotations and helps predict behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two well-structured sentences, front-loaded with the primary action and resource. The second sentence adds useful timezone context without waste. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only fetch with three optional parameters and strong annotations, the description is mostly adequate. It explains the single-date scope and timezone defaults. However, it does not clarify the exact time range for an entry on a given date (e.g., 00:00–23:59), which could be relevant for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds marginal value by clarifying timezone fallback behavior, which is partially redundant with the schema. It does not add significant new parameter semantics beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool fetches Toggl Track v9 time entries for a single date, using a specific verb ('fetch') and resource ('time entries'). It distinguishes itself from the sibling tools (ping, check_auth) which are unrelated to time entry retrieval.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for a specific date ('single date') and provides context on timezone handling, making it clear when this tool is appropriate. However, it does not explicitly mention what to use for other scopes (e.g., multiple dates or ranges), as no alternative among siblings directly relates.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Health check tool. Returns "ok".
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, indicating a safe, repeatable operation. The description adds the specific return value ('ok'), which is useful behavioral context beyond the annotations. It does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences ('Health check tool. Returns "ok".') with no wasted words. It is front-loaded with the essential purpose and immediately states the output, making it highly concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple health check tool with no parameters, no output schema, and clear annotations, the description is sufficient. It states the purpose and the return value, which is all the agent needs to know to invoke and interpret the result.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and schema coverage is trivially 100%. With no parameters to document, the baseline of 4 applies, and the description appropriately avoids unnecessary parameter details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description states 'Health check tool. Returns "ok"' which clearly identifies the tool as a health check and its output. This distinguishes it from siblings like get_time_entries_for_date and check_auth, which serve different purposes. However, it lacks specificity about what exactly is being checked (e.g., API availability, database connectivity).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives. There is no mention of using it before other operations or for verifying service health. The description does not discuss exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.0check_authget_time_entries_for_datepingScored across 3 tools
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.
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.
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.
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.
Read time entries, projects, clients, tasks and invoices; log and update tracked time.
Current time, timezone conversion & date math for AI agents. On Cloudflare Workers.
Time zone conversion, meeting-slot finding across countries, DST checks and .ics invites. All.
Convert and compare dates and times across any timezone with flexible, locale-aware formatting. Ad…