yt-toggl-mcp
Provides tools for managing Toggl Track time entries, timers, projects, clients, tags, and reports via the Toggl Track API v9.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
yt-toggl-mcp
A small, self-hosted MCP server for Toggl Track (API v9). It runs over stdio and exposes time tracking, projects/clients, and reporting to any MCP client.
No telemetry. The only network egress is to api.track.toggl.com. Workspace-level tokens are
stripped from every response and user emails are masked.
Tools
Tool | What it does |
| Verify the token; returns the (masked) user and accessible workspaces. |
| Read-only: effective workspace, project, and billable default with their source ( |
| Remaining API requests and reset time per organization. |
| List accessible workspaces. |
| List projects in a workspace. |
| List clients in a workspace. |
| List tags in a workspace. |
| Return the running timer with elapsed seconds. |
| Load a single entry by id. |
| List entries for a |
| Create a completed entry ( |
| Edit an existing entry; only the fields you pass are changed. A zero |
| Permanently delete an entry. |
| Start a running timer with optional description, project, tags. |
| Stop the running timer (or a specific |
| Total time for a range, grouped by project, sorted by hours. |
workspace_id defaults to the configured workspace and project_id defaults to the configured
project from the project settings file; explicit arguments always win. Timer operations are bound to
a configured workspace: repeating that workspace_id is accepted, naming another one fails with
CONFIGURED_WORKSPACE_MISMATCH instead of tracking in the wrong place. Without workspaceId, the
workspace comes from the call or the sole accessible workspace, and a project-only default is
applied only if the resolved workspace owns that project.
toggl_get_configuration reports those effective values and where each came from, so a caller can
see the defaults instead of guessing ids: configuration (in the settings file), derived (a
server fallback such as the sole workspace or billable: false), or unset. Error results carry a
category — invalid_argument, configuration, authentication, or upstream — so a bad argument
is not mistaken for an expired token.
Binding applies to timer writes only. toggl_list_projects, toggl_list_clients, toggl_list_tags,
and toggl_report still accept any accessible workspace_id, because browsing or reporting across
workspaces is a read that changes nothing; toggl_report scopes its totals to the workspace it
resolved, so name one deliberately when you mean another.
period accepts today, yesterday, week, lastWeek, month, lastMonth. Ranges are
interpreted in local time and end_date is inclusive at the tool boundary. since takes unix
seconds and, per Toggl, also returns entries deleted since that time.
Toggl enforces a sliding-window request quota per user per organization; on 402 the error
result carries quota_remaining and quota_resets_in_seconds.
toggl_report clips every entry to the requested range, so an entry crossing a boundary is neither
double-counted nor dropped. It scans backward in 84-day windows and respects Toggl's historical
retention boundary: if it reaches that boundary it returns incomplete: true together with
incomplete_reason, rather than reporting a silently short total. Any other error is propagated.
Related MCP server: clockify-mcp
Configuration
Toggl configuration has two scopes, and each setting lives in exactly one place.
User scope — the API token. TOGGL_API_KEY, or a per-tool file under your home directory
matching the other yt-* MCP servers:
~/.yt-toggl-mcp/credentials.json{
"apiToken": "<your token>"
}Project scope — the tracking defaults. The server reads .yt-toggl-mcp.json from its working
directory, which is the project root the MCP client launches it in. The name is fixed: there is no
flag and no search up the tree, so a project either has its own Toggl defaults or has none.
{
"workspaceId": 1234567,
"projectId": 216478744,
"billable": true
}apiToken must come from one of the two sources, otherwise the server exits with a message naming
the file to create. workspaceId/projectId in the user file are ignored.
File | Scope | Where | Keys |
| user | home directory |
|
| project | repository root |
|
Variable | Required | Default | Purpose |
| no |
| Toggl Track API token (track.toggl.com/profile). |
| no |
| Metadata cache TTL in ms. |
A token must come from one of the two sources, otherwise the server exits with a message naming the
file to create. The toggl-setup skill (.opencode/skills/toggl-setup/SKILL.md) walks a project
through creating the settings file, and the toggl-configuration skill
(.opencode/skills/toggl-configuration/SKILL.md) covers verifying the effective defaults and
switching tasks without overriding them. An apiToken key in the settings file is rejected,
because a project file may be committed by mistake while the token stays user-scoped.
A missing settings file does not stop the server: it logs a warning to stderr, the read tools keep
working, and every timer write fails with PROJECT_SETTINGS_MISSING — recording nothing rather
than an entry with no project — unless a verified project_id is passed for a one-off entry. A
malformed file or an invalid id still stops startup.
Both keys in the project file are optional: omit workspaceId if you only have one workspace, and
omit projectId if you do not want a default project.
billable is optional too, and it is what makes tracked time show as billable by default. A Toggl
project's own billable setting does not propagate to the entries created in it, so without this key
every new timer starts unbilled. It applies to toggl_start_timer and toggl_create_time_entry
when the caller passes no billable, and only where the configured project applies; an explicit
billable argument always wins. A value that is not true/false stops startup with the key named.
projectId is used only where it belongs, and is verified against the workspace before any write,
so an entry never lands in the wrong project. When workspaceId is set, the project applies while
tracking in that workspace and a stale id fails with INVALID_PROJECT_ID. Without workspaceId,
the project is applied when the resolved workspace owns it and ignored when it does not; that check
costs an extra request per write, and the result carries a notice when the project was skipped.
Keep .yt-toggl-mcp.json out of version control so no Toggl ids or personal tracking defaults
appear in tracked repository files, and add it to each project's .gitignore.
Where the file is found
The server looks for .yt-toggl-mcp.json in its working directory, then in its parent directories up
to the repository root (the nearest .git). A client that launches the server from anywhere inside
the repository therefore finds the file, so no extra configuration is needed. A launch outside the
repository finds nothing and the server warns.
No flag or environment variable selects another location: one repository, one
.yt-toggl-mcp.json. A missing file does not break the server — reads keep working and timer
writes fail with PROJECT_SETTINGS_MISSING without recording anything — so a repository starts
unconfigured and stays that way until someone configures it. Setup is never automatic: the agent
runs the toggl-setup skill only when the user explicitly asks to configure Toggl for the
repository.
Precedence, highest first:
explicit tool arguments (
workspace_id,project_id), where a configuredworkspaceIdaccepts only its own id.yt-toggl-mcp.jsonfrom the launch directory up to the repository root
A malformed settings file, or an id that is not a positive integer, stops the server with the path
and key named. workspaceId and projectId in the user credentials file are ignored: they belong
in the project settings file.
TOGGL_DEFAULT_WORKSPACE_ID was removed in 0.5.0 and --settings was removed in 0.7.0; put
workspaceId and projectId in the project settings file instead.
Install
Prerequisites: Node.js >=20.19.0 and a Toggl Track API token from
track.toggl.com/profile (scroll to the bottom → "Click to reveal").
npm
npx -y yt-toggl-mcpRun it from a repository that has a .yt-toggl-mcp.json; without one the server still starts but warns, and writes that need a project default fail.
Any MCP client that speaks stdio works. The server reads its project settings from the working directory, so every config must launch it from the repository root. Generic client config:
{
"mcpServers": {
"yt-toggl-mcp": {
"command": "npx",
"args": ["-y", "yt-toggl-mcp"]
}
}
}yt-toggl-mcp --help prints the credential and project settings paths, the precedence, and the
environment variables; --version prints the version. Both write to stderr, since stdout carries
the MCP protocol.
opencode
1. Create the credentials file
Write ~/.yt-toggl-mcp/credentials.json (Windows: C:\Users\<you>\.yt-toggl-mcp\credentials.json):
{
"apiToken": "<your token>"
}Alternatively set TOGGL_API_KEY in the environment to supply the token.
2. Register the server
Add this to ~/.config/opencode/opencode.jsonc (Windows:
C:\Users\<you>\.config\opencode\opencode.jsonc) under the existing mcp key. <repo> is the
repository whose .yt-toggl-mcp.json the server should read:
{
"mcp": {
"yt-toggl-mcp": {
"type": "local",
"command": ["npx", "-y", "yt-toggl-mcp"]
}
}
}No environment block is needed: the server reads its own credentials file, like yt-gmail-mcp
and yt-zoho-mcp.
3. Configure when you want to track
A repository starts unconfigured: reads work, starting or creating a timer fails with
PROJECT_SETTINGS_MISSING and records nothing. Ask opencode to configure Toggl for this repository
when you want to track time here. It then runs the toggl-setup skill — checks the token, guides
authorization if needed, lists
the workspaces and projects, asks which project this repository should use, writes the file, and
adds it to .gitignore. It does not do this on its own, and not on the first message.
The server finds the file by walking up from its launch directory to the repository root, so one
global yt-toggl-mcp entry covers every repository.
4. Restart opencode
Config is read once at startup and is not hot-reloaded, so the server only loads after a restart.
5. Verify
Ask opencode to call toggl_check_auth. It should return your (masked) account and workspace list.
A quick win after that: ask "what am I currently tracking?".
Development
npm install
npm run build
npm run lint
npm testnpm test runs the Vitest suite with HTTP mocked, so no token or live calls are needed.
The server runs from src in development (npm run dev, npm test). dist is only for the
published bin: npm install compiles it through the prepare script, and npm run build does
the same on demand.
node dist/index.js runs the built server locally — it reads the same credentials and project
settings files described above, so run it from the project root. npm run dev watches the source
with tsx instead of building.
License
MIT © yentsun — see LICENSE.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Toggl 2.0 MCP server for tasks, projects, time entries, and workspace operations.
timesheet.io MCP server - manage timers, projects, tasks and reports
Official Todoist MCP server. Manage tasks and projects. Hosted, no API key needed.
Manage Timequip projects, tasks, comments, members, and dashboards through MCP.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceAn MCP server for Traggo, a tag-based time tracking tool. Manage time spans, timers and tags, get useful stats.GPL 3.0
- AlicenseBqualityDmaintenanceMCP server for Clockify time tracking, enabling CRUD operations on workspaces, projects, tasks, clients, tags, users, and time entries.36MIT
- AlicenseAqualityCmaintenanceA standalone MCP server that exposes the ATimeLogger REST API to Claude Desktop/Code over stdio, enabling activity tracking (start/stop/pause/log), reports/history, and activity type management.854 npm1MIT
- AlicenseAqualityCmaintenanceMCP server for Toggl Focus 2.0, enabling project, task, and time-entry management with live timer control through natural language.2412 npmMIT