Read and write your Timely time tracking from Claude.ai and Claude Code. Covers the whole account: hours, projects, clients, users, labels, teams, planned work and reports. An OAuth 2.1 login sits in front so it can be added to Claude.ai as a custom connector, and Claude Code can use a plain token instead.

Tools

Reading

Writing

Every update is a patch: only what you pass changes, so a rename never blanks the other fields.

Reports

timely_report returns totals grouped by client, user, label and day. It summarises by default, because a month across an account is hundreds of kilobytes of repeated duration and cost objects, which is rarely what a summary needs:

{"since": "2026-08-01", "upto": "2026-08-31"}

Pass detail: true for every underlying entry.

How it fits together

Claude.ai / Claude Code
        |  HTTPS
   Cloudflare Tunnel, or any proxy that gives you HTTPS
        |
   nginx  127.0.0.1:8451
        |
   auth-server.cjs  :8452    handles the login and the tokens
        |
   timely-mcp  :8450         the server itself, local only
        |
   api.timelyapp.com

The MCP has no login of its own and refuses to listen on anything but the local machine, so everything reaching it has already passed the login. That login takes either an OAuth token, which is what Claude.ai negotiates, or a fixed token, which is quicker for Claude Code.

Setup

Create an OAuth app at https://app.timelyapp.com/<account_id>/oauth_applications with redirect URI http://localhost:3000/callback, then:

git clone https://github.com/rollecode/timely-mcp-server.git
cd timely-mcp-server
bun install && npm install --omit=dev

cp .env.example .env      # add TIMELY_CLIENT_ID and TIMELY_CLIENT_SECRET
bun auth.ts               # opens the browser, writes .tokens.json

For the remote setup, move the tokens somewhere the service can write and set a password:

mkdir -p ~/.config/timely-mcp && chmod 700 ~/.config/timely-mcp
cp .tokens.json ~/.config/timely-mcp/tokens.json
chmod 600 ~/.config/timely-mcp/tokens.json

CONFIG_DIR=~/.config/timely-mcp node set-password.cjs 'your-password-here'
openssl rand -hex 32 > ~/.config/timely-mcp/token
chmod 600 ~/.config/timely-mcp/token

Fill in YOUR_USER and the hostname in systemd/*.service and nginx/timely-mcp.conf, then:

sudo cp systemd/*.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now timely-mcp timely-mcp-auth

sudo cp nginx/timely-mcp.conf /etc/nginx/sites-enabled/timely-mcp
sudo nginx -t && sudo systemctl reload nginx

Point a tunnel or an HTTPS proxy at 127.0.0.1:8451. OAuth needs HTTPS.

Check from outside: discovery returns metadata, and /mcp without a token must return 401.

curl https://your-host/.well-known/oauth-authorization-server
curl -o /dev/null -w '%{http_code}\n' -X POST https://your-host/mcp

Connecting

Claude.ai: Settings, Connectors, Add custom connector, https://your-host/mcp, client ID and secret blank.

Claude Code:

claude mcp add --transport http timely https://your-host/mcp \
  --header "Authorization: Bearer $(cat ~/.config/timely-mcp/token)" --scope user

Without a server, Claude Code can run it directly over stdio:

claude mcp add timely -- bun /path/to/timely-mcp-server/server.ts

Settings

The Timely access token refreshes itself when it expires; the refresh token is written back to TIMELY_TOKENS_PATH.

Credits

The login layer comes from rollecode/obsidian-remote-mcp. Timely and its logo belong to Memory AS.