mcp-timely

An MCP server for Timely time tracking, built for asking questions rather than wrapping endpoints. It is for Timely users who want Claude, or any other MCP client, to answer "where did my time go?" reliably. Its three questions are each answered in a single upstream call with Timely doing the aggregation server-side, so the model never pages through raw entries to sum hours (and never gets the sum wrong). Four write tools log time, correct entries that were logged wrong, and mark invoiced hours billed.

Everything is scoped to the authorized user; there are no user or team parameters. update_entry and delete_entry refuse entries that are billed, invoiced, locked, running a timer, or belong to someone else. When Timely rejects a change, the error carries Timely's reason (for example labels the target project does not allow).

Requirements

• Python 3.12 or newer and uv

• FastMCP 4 (fastmcp>=4.0.10,<5.0.0, installed by uv sync)

• A Timely account and a Timely OAuth application

• Docker, only for the containerized HTTP deployment

Related MCP server: time-tracker-mcp

Setup

1. Create a Timely OAuth app at https://app.timelyapp.com/<account>/oauth_applications with callback URL urn:ietf:wg:oauth:2.0:oob.

2. Configure

   cp .env.example .env   # fill in TIMELY_CLIENT_ID and TIMELY_CLIENT_SECRET

3. Authorize (once)

   uv sync
   uv run mcp-timely auth

   Open the printed URL, authorize, paste the code. Tokens land in TIMELY_TOKEN_FILE (default timely_tokens.json) and refresh themselves from then on.

4. Add to Claude Code (stdio)

   claude mcp add timely -- uv run --directory /path/to/mcp-timely mcp-timely

Configuration

Settings come from environment variables (see .env.example).

Authentication

There are two separate credentials:

• Upstream (Timely): OAuth 2.0, bootstrapped once with mcp-timely auth. Timely rotates refresh tokens on every refresh and its access tokens carry no expiry. The server uses the access token until a 401, then refreshes once, writes the new pair atomically before continuing, and retries the request once. The token file is the only state. Running mcp-timely auth again rotates the token family, so any other running instance needs the new file. Otherwise re-authorization is only needed if the grant is revoked.

• Clients (HTTP only): with TRANSPORT=http, every request needs Authorization: Bearer <MCP_API_KEY> (constant-time compare). The server refuses to start over HTTP without a key.

HTTP deployment

TRANSPORT=http serves streamable HTTP on /mcp and liveness on /health (also /healthz). The Dockerfile builds a non-root image with the token file at /data/timely_tokens.json; compose.yaml runs the published image on host port 8011 with a persistent timely-data volume. Run mcp-timely auth first and place the resulting token file in that volume.

docker compose up

Usage telemetry

A small middleware (src/mcp_timely/usage.py) writes one JSON line per tool call to stderr: server name, tool name, duration, outcome and MCP protocol version. It never records arguments or results. Tool failures raise ToolError, so they are logged with outcome: error.

Development

uv sync
uv run pytest        # in-memory MCP client, no network
uv run ruff check .

CI (.github/workflows/ci.yml) runs ruff and the tests as the test check, which is required before a pull request can merge into main.

Releases

Every push to main that touches non-doc files releases automatically: tests and a security audit run, the next vX.Y.Z tag is pushed (no version-bump commit), and a multi-arch image is published to ghcr.io/caseyro/mcp-timely with that version baked in (reported by /health). Consequences:

• The git tag is the version; version in pyproject.toml is not bumped.

• Add [skip ci] to a commit message to skip a release.

• Markdown-only and test-only changes don't trigger a release.

Support

If this server saves you time, you can buy me a coffee.

License

MIT, see LICENSE.