ATimeLogger MCP Server
Summary: It's an MCP server that gives Claude read/write access to a user's ATimeLogger time-tracking account — running timers, retroactive logging, and reports.
See what's running —
get_current_statusshows running/paused activities with elapsed time;list_activity_typesreturns the user's activity types as a group tree (names for talking to the user, ids for exact targeting).Control timers —
start_activity(by type name, fuzzy matched, or id) andstop_activity(name optional if only one activity is active), both with optional backdating via a wall-clockattime orstarted/stopped_minutes_ago.Pause and resume —
pause_resume_activitywithaction: pause|resume.Log past time —
log_intervalretroactively creates a completed entry fromfrom/towall-clock times, optionally with a comment and tags.Reports —
time_reportgives aggregated per-type totals with per-DAY/WEEK/MONTH buckets, for named periods (today,this_week,last_month, …) or explicitfrom/to, filtered by type names/ids or tags.History —
list_intervalsreturns raw entries grouped by day, paged (page,sizeup to 50 days), capped at a 100-day range, with the same period/type/tag filters.Timezone-aware — any tool that shows or accepts times takes an optional IANA
timezone(default: the user's ATimeLogger timezone).Both local and remote — usable over stdio from Claude Desktop/Code, or served over Streamable HTTP (with an
MCP_AUTH_TOKEN) for remote MCP clients like Notion custom agents.
Caveat: the supplied schema exposes only these eight tools — the README's update_activity (editing comments/tags) and app_help are not present, and there is no way to edit interval times or delete entries.
Allows Notion custom agents to interact with ATimeLogger through a remote MCP endpoint.
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., "@ATimeLogger MCP Server Show my current activity status."
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.
ATimeLogger MCP Server
A standalone MCP (Model Context Protocol) server that exposes the ATimeLogger REST API to Claude Desktop / Claude Code over stdio. Scope: activities (start/stop/pause/log/update), reports/history, activity types, and official app documentation.
Setup
Requires Node 20+.
Generate a Personal Access Token in the ATimeLogger web app: Settings → API Tokens → Generate token. The value (starting with
atl_pat_) is shown only once — copy it right away. You can revoke the token from the same page at any time.Build the server and register it:
npm install
npm run build
npm run setup # paste the token, verifies it, prints the registration commandThe setup script prints ready-to-use registration snippets for both clients:
Claude Code — a one-liner:
claude mcp add atimelogger \
-e ATL_TOKEN=atl_pat_... \
-- node /absolute/path/to/atimelogger-mcp/dist/index.jsClaude Desktop — a JSON block to merge into ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows), then restart Claude Desktop:
{
"mcpServers": {
"atimelogger": {
"command": "node",
"args": ["/absolute/path/to/atimelogger-mcp/dist/index.js"],
"env": {
"ATL_TOKEN": "atl_pat_..."
}
}
}
}The server targets production (https://app.atimelogger.pro) by default — no URL configuration needed. To work against a different backend, set ATL_BASE_URL explicitly: pass --url <base-url> to the setup script (or set the env var), and it will include ATL_BASE_URL in the printed snippets. Generate the token in the web UI of the same server you point the MCP at.
Troubleshooting: a 401 from any tool means the token is invalid, expired, or was revoked — generate a new one in Settings → API Tokens and update ATL_TOKEN in the MCP config.
Related MCP server: jira-worklog-mcp
Remote server (for Notion custom agents & other remote-MCP clients)
The same tools can be served over the network via the Streamable HTTP MCP transport, so a hosted client such as a Notion custom agent can connect by URL instead of spawning a local process.
npm install
npm run build
ATL_TOKEN=atl_pat_... MCP_AUTH_TOKEN=some-long-secret npm start
# → Streamable HTTP MCP endpoint on http://0.0.0.0:3000/mcp (health: /health)Environment variables (see .env.example):
Var | Required | Purpose |
| yes | ATimeLogger Personal Access Token the server acts as |
| recommended | shared secret required to call |
| no | non-production backend (defaults to |
| no | listen port (default |
| no | endpoint path (default |
One deployment = one ATimeLogger account (the server acts as the single
ATL_TOKEN). Because the URL is internet-facing, setMCP_AUTH_TOKENand serve it over HTTPS.
Getting a public URL
One-click (Render) — after this repo is on your GitHub, click the button (or replace the URL with your fork):
Render reads the bundled render.yaml, then prompts you for the two secrets ATL_TOKEN and MCP_AUTH_TOKEN. When it finishes, your endpoint is https://<service>.onrender.com/mcp.
Other options:
Docker / VPS —
docker compose up -d --build(fill.envfirst), then put HTTPS in front (Caddy/Nginx/Cloudflare Tunnel).Any Node 20+ host works:
npm ci && npm run build && npm start.
Detailed, step-by-step deploy + config (Chinese): DEPLOY.zh-CN.md.
Connect it to Notion
Open your Notion custom agent → Tools and access → add an MCP server, paste the …/mcp URL, and provide the MCP_AUTH_TOKEN as the bearer/access token. Full step-by-step (Chinese): NOTION_MCP_GUIDE.zh-CN.md. Design/rationale: docs/REMOTE_MCP_DESIGN.zh-CN.md.
Tools
Tool | Purpose |
| Running/paused activities with elapsed time |
| Activity type names as a group tree (source of names for other tools) |
| Start by type name; optional backdating ( |
| Stop the active activity (name optional if only one is active); same backdating options |
| Pause or resume |
| Retroactively log a completed entry (wall-clock times, optional comment/tags) |
| Update the comment and/or tags of an existing entry (running or past) without changing its tracked time; get |
| Aggregated per-type statistics for a period ( |
| Raw history grouped by day, paged, max 100-day range; entries carry the |
| Official app documentation (atimelogger.pro/docs) — the assistant looks up how app features work (goals, widgets, sync, export, …) instead of guessing |
Tools accept human-readable type names (fuzzy matched); internal ids also flow through tool outputs and parameters for exact targeting, but are never shown to the user. Durations are returned as "2h 15m" strings; times are shown in the user's ATimeLogger timezone unless a timezone parameter is given.
Usage examples
Things you can say to your assistant once the server is registered:
Timers
"Start tracking work" · "Stop the timer" · "Pause reading, I'll be back in 10" · "What am I tracking right now?"
Backdating — forgot to press start or stop:
"Start Development — I actually began at 11:30" · "Stop work, I finished 20 minutes ago" · "I've been in a meeting since 14:00, track it"
Logging past activities
"Log 2 hours of Reading yesterday from 9 to 11pm" · "Add a gym session for last Saturday morning, 90 minutes, tag it 'legs'" · "I slept from 23:30 to 7:15, log it"
Annotating existing entries
"Add a comment to the timer that's running: pair-programming with Lisa" · "Tag yesterday's gym entry 'legs'"
Reports & history
"Where did my week go?" · "How much did I work in June, broken down by week?" · "Compare my sleep this month vs last month" · "Show everything I tracked today" · "Which day last week had the most Development time?"
Combinations — the assistant chains tools on its own:
"Stop whatever is running and start Work" · "Continue from where the last entry ended — start Development from that time" · "Fill yesterday's gap between lunch and the meeting with Reading"
Activity names are fuzzy-matched against your own type list, so "start dev" finds "Development"; the assistant asks when a name is ambiguous.
Limitations
start_activitycannot attach a comment (the underlying start endpoint takes only a type and time); add one afterwards withupdate_activity, or uselog_intervalfor retroactive entries with comments/tags.Only comments and tags of existing entries can be edited (
update_activity); interval times cannot be changed and entries cannot be deleted — use the ATimeLogger app for that (the assistant can explain how viaapp_help).History requests are capped at 100 days by the backend.
Available Tools
8 toolsget_current_statusA
Show currently running or paused activities with elapsed time.
Inputs: timezone.
list_activity_typesA
List the user's activity types as a tree (groups contain children): names plus internal ids. Use the names when talking to the user; use the ids for exact targeting in other tools.
Inputs: include_archived.
list_intervalsA
List raw time entries (intervals) grouped by day for a date range (max 100 days). Paged by day — use page for older days.
Inputs: to, from, page, size, +5 more.
log_intervalA
Retroactively log a completed time entry for an activity type. Times are wall-clock in the user's timezone, format "yyyy-MM-dd HH:mm".
Inputs: to (required), from (required), tags, comment, +3 more.
pause_resume_activityB
Pause a running activity or resume a paused one.
Inputs: action (required), type_name, activity_id.
start_activityA
Start tracking an activity by type name (fuzzy matched, see list_activity_types) or type_id. Optionally backdate the start with at (wall-clock) or started_minutes_ago.
Inputs: at, type_id, timezone, type_name, +1 more.
stop_activityA
Stop a running or paused activity. type_name may be omitted when exactly one activity is active. Optionally backdate the stop with at (wall-clock) or stopped_minutes_ago.
Inputs: at, timezone, type_name, activity_id, +1 more.
time_reportA
Aggregated time statistics per activity type for a date range. Returns overall totals plus per-DAY/WEEK/MONTH buckets.
Inputs: to, from, tags, period, +4 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 8 tools
Each tool addresses a distinct aspect of time tracking: listing types, checking current status, starting/stopping/pausing activities, logging entries retroactively, and generating reports or raw interval data. There is no overlap between tools; even pause_resume_activity is clearly a single combined operation.
All tool names use snake_case and mostly follow a verb_noun pattern (list_activity_types, start_activity, stop_activity, log_interval, list_intervals). The one exception is time_report, which is noun_noun rather than verb_noun, but it is still clear and fits the overall style.
With 8 tools, the server is well-scoped for its purpose of tracking time. Each tool covers a necessary action without redundancy, and the count sits comfortably in the ideal range for a focused domain.
The tool set covers the full tracking lifecycle: starting, stopping, pausing, resuming, retroactively logging, retrieving current status, viewing raw intervals, and generating aggregated reports. There are no obvious dead ends, as every tracking action has a corresponding read or management tool.
Maintenance
Related MCP Connectors
timesheet.io MCP server - manage timers, projects, tasks and reports
Toggl 2.0 MCP server for tasks, projects, time entries, and workspace operations.
Shared memory MCP server for Claude Code, Codex, Gemini CLI and Cursor. Cited, editable.
MCP server exposing klokin time-tracking operations (employees, time entries, stores) to AI clients.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceA Model Context Protocol (MCP) server that connects to ActivityWatch, allowing LLMs like Claude to interact with your time tracking data.67 PyPI5MIT
- FlicenseAqualityCmaintenanceMCP server for logging and checking Jira Cloud worklogs from AI agents such as Claude Code, Claude Desktop, Cursor, or any MCP client that supports stdio.71-
- AlicenseNot gradedqualityBmaintenanceMCP server for Timely time tracking API. Connects Claude Code to your Timely account for reading and creating time entries, projects, tasks, and users.9MIT
- AlicenseNot gradedqualityAmaintenanceEnables logging time entries to Clockify via LLM agents, supporting bulk creation, project lookup by name, and local timezone handling. A local stdio MCP server that converts natural language time requests into Clockify API calls.704 npm1MIT