Atimelogger MCP server

ATimeLogger MCP Server

A standalone MCP (Model Context Protocol) server that exposes the ATimeLogger REST API to AI assistants — locally over stdio (Claude Desktop / Claude Code / OpenAI Codex) or remotely as a connector (claude.ai in the browser, Claude mobile apps, ChatGPT). Scope: activities (start/stop/pause/log), reports/history, and activity types.

The same package also installs atimelogger-cli — a read-only JSON CLI that needs no AI assistant at all. Use it from cron jobs, status bars, and shell pipelines; it shares the server's internals (fuzzy type names, period words, DST-correct timezones) but runs entirely on its own. A library entry point covers the third case, calling ATimeLogger in-process from your own code.

Setup

Requires Node 20+.

1. Generate a Personal Access Token in the ATimeLogger web app: Settings → API Tokens → Generate token. The value (starting with atlpat) is shown only once — copy it right away. You can revoke the token from the same page at any time.

1. Register the server. No install or build step needed — npx fetches the published package on first run:

Claude Code — a one-liner:

claude mcp add atimelogger \
  -e ATL_TOKEN=atl_pat_... \
  -- npx -y atimelogger-mcp

Claude Desktop — a JSON block to merge into ~/Library/Application Support/Claude/claudedesktopconfig.json (macOS) or %APPDATA%\Claude\claudedesktopconfig.json (Windows), then restart Claude Desktop:

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

OpenAI Codex (CLI, IDE extension, or the ChatGPT desktop app's Codex mode) — also a one-liner; the configuration is shared by all three Codex surfaces:

codex mcp add atimelogger --env ATL_TOKEN=atl_pat_... -- npx -y atimelogger-mcp

Equivalent ~/.codex/config.toml block:

[mcp_servers.atimelogger]
command = "npx"
args = ["-y", "atimelogger-mcp"]
env = { "ATL_TOKEN" = "atl_pat_..." }

MCP support in Codex is not gated by plan — it works with any ChatGPT subscription that includes Codex, or with a plain API key. (Using the tools from the ChatGPT web/mobile app is a different path — see Connect from ChatGPT below.)

Running from source

Instead of the published package, you can clone and build:

git clone https://github.com/zaplitny/atimelogger-mcp && cd atimelogger-mcp
npm install
npm run build
npm run setup        # paste the token, verifies it, prints registration snippets pointing at the local build

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.

No token yet? The server also starts without ATLTOKEN in docs-only mode: the apphelp tool (official app documentation) works, so you can ask your assistant how ATimeLogger features work before setting up API access; the time-tracking tools return setup instructions until a token is configured.

Tools

Shortened. The full README is on GitHub.