# atimelogger-mcp [Health: Active]

**Category:** 🏢 Workplace & Productivity  
**Repository:** https://github.com/zaplitny/atimelogger-mcp  
**GitHub Stars:** 19  
**npm Downloads (last month):** 196  
**Views:** 5  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/atimelogger-mcp

## Description
MCP server exposing the ATimeLogger REST API (activities, reports, types)

## Tools
Capabilities this server exposes over MCP:

- **list_activity_types** — 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.
- **get_current_status** — Show currently running or paused activities with elapsed time.
- **start_activity** — 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.
- **stop_activity** — 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.
- **pause_resume_activity** — Pause a running activity or resume a paused one.
- **log_interval** — 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".
- **update_activity** — Update the comment and/or tags of an existing entry (running, paused, or stopped) without changing its tracked time. Use this instead of logging a new entry when the user wants to annotate, describe, or re-tag something already tracked. Get activity_id from get_current_status (active timers) or list_intervals (past entries).
- **time_report** — Aggregated time statistics per activity type for a date range. Returns overall totals plus per-DAY/WEEK/MONTH buckets.
- **list_intervals** — List raw time entries (intervals) grouped by day for a date range (max 100 days). Paged by day — use `page` for older days.
- **app_help** — Official ATimeLogger app documentation. Use it to answer any question about how the app works, or how to do in the app what these tools cannot (edit entry times, delete records, goals, widgets, CSV export, sync, backups, Pomodoro, Premium features). Call with no arguments for the table of contents (its note covers platform applicability), then again with `topics` to fetch the relevant pages — answer from the docs, not from memory. Cross-references like `sync.md` inside a page point to the topic with that slug.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "atimelogger-mcp": {
    "command": "npx",
    "args": ["-y","atimelogger-mcp"],
    "env": {
      "ATL_TOKEN": ""
    }
  }
}
```

**Requires environment variables:** `ATL_TOKEN` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What atimelogger-mcp does

The atimelogger-mcp MCP server connects an MCP-compatible assistant to an ATimeLogger account through the service's REST API. It covers active timers, activity types, completed intervals, annotations, reports, and history. The server supports both read operations and changes to tracked time, so it can handle requests such as starting work, stopping a timer, adding a past meeting, or tagging an existing entry.

Activity types are addressed by human-readable names and matched approximately against the account's type list. If a name is ambiguous, the assistant can ask for clarification. Internal identifiers may pass through tool inputs and outputs for precise targeting, but they are not shown as the primary user-facing names.

## How it works

The atimelogger-mcp MCP server communicates locally over stdio. An MCP client launches the package with Node.js, and the server uses the configured ATimeLogger token for authenticated API calls. The package can be started with `npx`, so a separate build is not needed when using the published package. Node.js 20 or newer is required.

Time controls include starting, stopping, pausing, and resuming activities. Start and stop operations can use either a wall-clock timestamp or a number of minutes in the past, which supports correcting missed timer actions. Completed intervals can be logged retroactively with start and end times, comments, and tags. Existing entries can have their comments or tags changed without changing their recorded times.

Reports accept named periods such as `today`, `this_week`, and `last_month`, or explicit dates. History is returned by day and supports paging, with a maximum requested range of 100 days. Durations are presented as readable strings, and times use the ATimeLogger account timezone unless a tool request supplies another timezone.

## Setup and configuration

Create a personal access token in the ATimeLogger web app under Settings, API Tokens, and Generate token. The token is displayed once and can later be revoked. Set it as `ATL_TOKEN` in the MCP client's configuration.

Claude Code, Claude Desktop, and OpenAI Codex can register the server with an `npx -y atimelogger-mcp` command. Claude Desktop requires adding an MCP server entry to its configuration file and restarting the application. The repository also documents running from source by cloning the project, installing dependencies, building it, and using the setup command.

The server can start without `ATL_TOKEN` in docs-only mode. In that state, `app_help` remains available and the time-tracking tools return setup guidance instead of accessing account data. Authentication failures generally indicate an invalid, expired, or revoked token.

## Tools and capabilities

The atimelogger-mcp MCP server provides these tools:

- `get_current_status` reports running or paused activities and elapsed time.
- `list_activity_types` returns the account's activity type tree.
- `start_activity`, `stop_activity`, and `pause_resume_activity` control timers.
- `log_interval` records a completed interval with optional comments or tags.
- `update_activity` edits comments or tags on current or historical entries.
- `time_report` returns aggregated statistics by activity type.
- `list_intervals` returns raw, day-grouped history with pagination.
- `app_help` retrieves official ATimeLogger documentation about features such as goals, widgets, synchronization, and export.

The same package also installs `atimelogger-cli`, a read-only JSON command-line tool for status, types, reports, intervals, and diagnostics. It is separate from MCP use and does not start, stop, or edit activities. An experimental library entry point is also available for in-process use by applications such as daemons or editor plugins.

## Limitations and notes

The server depends on an ATimeLogger personal access token for account operations and the ATimeLogger service being reachable. The history tool limits a requested range to 100 days. The command-line interface is intentionally read-only; write operations remain available through the MCP server. The `app_help` tool uses the official ATimeLogger documentation so assistants can look up application behavior instead of inferring it.

_Full upstream README: https://allmcps.com/mcp/atimelogger-mcp/readme_