Skip to content

Feature

An MCP server so your LLM can drive Hoursmith.

Mint a token, drop a six-line config into Claude Desktop / Cursor / Zed, or point an HTTP MCP client like Odin at the local endpoint, and your LLM has typed tools for every Hoursmith resource — clients, projects, tasks, time entries, expenses, invoices. Ask "log 90 minutes to Coffee Coders" and it happens. Open source on npm as `@hoursmith/mcp-server`. Studio+ for token access; Member tokens get a Member-scoped tool surface automatically.

Plans: Studio · Agency

Start freeSee pricing

Free for solo freelancers · No credit card required

What's in it

  • Drop-in for Claude Desktop, Cursor, Zed, Odin

    Use standard MCP stdio for process-spawning clients, or Streamable HTTP for clients that ask for a URL and API-key headers. `npx -y @hoursmith/mcp-server` does the install + run.

  • Every REST endpoint as a typed tool

    list_clients, create_time_entry, get_running_timer, archive_task, list_invoices, get_me, and the full set in between — every list_* tool takes search, filter, and sort parameters, so 'unpaid invoices for Acme, newest first' is one call. Zod schemas mean the LLM never sends a malformed request.

  • Role-aware out of the box

    The MCP server inherits the role of the token that mints it. Owner/Admin tokens see the whole workspace; Member tokens see only their assigned projects — same scope the UI would apply.

  • Errors round-trip with detail

    Validation failures, plan-gate denials (with `requiredPlan`), and conflict errors (invoiced-time-entry-locked, etc.) all surface back to the LLM as actionable text, not opaque "something went wrong".

  • Open source, MIT, on npm

    Fork it, audit it, vendor it. The server is a thin ~600-line TypeScript wrapper around the same REST API the OpenAPI doc describes — no hidden surface area.

  • Idempotent writes for safe retries

    Every POST tool generates an Idempotency-Key automatically. Network blips don't create duplicate clients or double-logged hours.

How it works

  1. 01

    1. Mint a token

    Settings → API → New token. Pick read or read+write, copy the `hsk_live_...` secret once.

  2. 02

    2. Add to your client's config

    For stdio clients, paste the standard MCP block: `command: "npx", args: ["-y", "@hoursmith/mcp-server"], env: { HOURSMITH_API_TOKEN: "hsk_live_..." }`. For HTTP clients, run with `HOURSMITH_MCP_TRANSPORT=http` and add your token as `Authorization` or `x-api-key`.

  3. 03

    3. Restart, then ask

    Restart the LLM client. Ask "what am I tracking right now?" or "log 45 minutes to the brand-refresh task, billable". The LLM picks the right tool.

  4. 04

    4. Rotate or revoke anytime

    Revoke the token at Settings → API → Revoke. The next tool call fails fast with 401; mint a new one, update the config, done.

Common questions

  • Does this require running a server I host?

    No for the standard stdio setup: the MCP server runs as a child process of your LLM client (Claude Desktop, Cursor, Zed). URL-only clients can run the same package as a local HTTP endpoint, usually at `http://localhost:8000/mcp/`; nothing needs to be deployed publicly.

  • Where is my token stored?

    Only in your LLM client's config file or in the HTTP client's per-request headers. The MCP server itself never writes the token anywhere; it reads it from env or the request header, sends it as a Bearer header to Hoursmith, done.

  • Can a Member's token do everything an Owner can?

    No. The MCP server inherits the role of the token's creator. A Member's token sees only the projects they've been added to and can only modify their own time entries — identical to what the UI shows them. We don't run shadow permissions.

  • Will I get charged anything to use this?

    Hoursmith API access is included on Studio and Agency plans (per-token rate limits apply — see the API page). The MCP server itself is open-source and free.

  • Is the MCP server reviewed?

    Yes — same security review pass as the underlying REST API. Token leakage paths, error messaging, idempotency, and HTTPS transport all covered. The full source is on npm; vendoring is encouraged for enterprise security teams.

Related

Try it free, in two minutes.

Create an account, set up your first client, and log an hour. The invoice will already be on the way to building itself.

Create your free account

Free for solo freelancers · No credit card · Cancel any time