timely-mcp-server

Timely MCP server

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.

Writes are checked against what Timely returns. Timely answers 200 for a field it silently drops, so a rate that did not land now raises an error instead of reporting a success that never happened.

Rates and billing

A project charges in one of three ways, set with rate_type: project bills every hour at the project rate, user bills each person at their own rate, and non-billable bills nothing. Timely refuses to create a project without one.

timely_project_rates puts the charge-out rate next to what each person costs, which is the difference the reports call profit:

{"user_id": 20991, "charged": 105, "costs": 87.17, "margin_per_hour": 17.83}

If profit looks wrong everywhere, check timely_get_user: when default_hour_rate equals internal_hour_rate every hour breaks even by construction. timely_update_user sets them apart.

timely_unrated_work lists projects that logged billable hours and earned nothing, with the reason for each. timely_set_events_billable fixes entries in bulk; Timely has no bulk endpoint, so it updates each entry in turn and leaves invoiced or locked ones alone. Preview with dry_run: true.

Budgets

budget_type takes hours or fees. Timely's own API wants the letters H and M and rejects the words its docs use, so the tools take the word and send the letter.

Reports

timely_report returns totals grouped by client, user, label, team 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"}

Each row carries hours split by billable and invoiced state, revenue, internal cost and profit, so what was earned and what it cost sit side by side. Pass detail: true for every underlying entry.

Filtering time entries

Timely's own /events endpoint accepts project_ids, user_ids, label_ids and billable and then ignores them, answering 200 with the entire account. timely_list_events reads through the routes that do filter and applies the rest itself, so asking for one person's hours returns one person's hours. Note it takes per_page, not limit, which Timely ignores here.

Related MCP server: ops-platform-mcp

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.