Skip to main content
Glama
CaseyRo

mcp-timely

by CaseyRo
OverviewSchemaRelated ServersScoreDiscussions
Python
Remote

mcp-timely

MCP server for Timely time tracking — built for asking questions, not wrapping endpoints. Three read-only tools, each answered in a single upstream call with Timely doing the aggregation server-side, so an LLM never pages through raw entries to sum hours (and never gets the sum wrong).

Tool

The question it answers

projects_overview

What's on my plate? — projects with client, logged hours, budget burn, unbilled amounts

time_spent

Where did my time go? — date-range rollups grouped by project, client, label, or day, with billable split

work_log

What did I actually do? — individual entries with notes for a range; standup/diary/invoicing material

Scope is deliberate: read-only, and always scoped to the authorized user. There are no write tools and no user/team parameters.

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

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

Related MCP server: timely-mcp-server

Token handling

Timely rotates refresh tokens on every refresh and its access tokens carry no expiry. The session layer uses the access token until a 401, then refreshes once — persisting the new pair atomically before continuing — and retries the request once. The token file is the only state; keep it on a persistent volume in Docker. Re-authorization is only needed if the grant is revoked.

HTTP deployment

Set TRANSPORT=http and MCP_API_KEY (the server refuses to start unauthenticated HTTP). Serves streamable-http on /mcp, liveness on /health. See compose.yaml.

Development

uv run pytest        # unit tests (in-memory MCP client, no network)
uv run ruff check .

Releases

Every push to main that touches non-doc files releases automatically: tests and a security audit run, the patch version bumps, a vX.Y.Z tag lands, and a multi-arch image is published to ghcr.io/caseyro/mcp-timely. Consequences:

  • Don't edit version in pyproject.toml by hand — CI owns it.

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

  • Rebase PRs on main before merging so the auto-bump commit doesn't race yours.

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

License

MIT

Install Server
A
license - permissive license
A
quality
B
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
–Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Tools

Related MCP Servers

View all related MCP servers

Related MCP Connectors

View all MCP Connectors

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/CaseyRo/mcp-timely'

If you have feedback or need assistance with the MCP directory API, please join our Discord server