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, 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

    Standard MCP stdio transport. Add a single `mcpServers.hoursmith` block to your client's config; `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. 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

    Paste the standard MCP block: `command: "npx", args: ["-y", "@hoursmith/mcp-server"], env: { HOURSMITH_API_TOKEN: "hsk_live_..." }`.

  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. The MCP server runs as a child process of your LLM client (Claude Desktop, Cursor, Zed). Your LLM client launches it, talks to it over stdio, and shuts it down with the app. Nothing for you to deploy.

  • Where is my token stored?

    Only in your LLM client's config file (e.g. `claude_desktop_config.json`). The MCP server itself never writes the token anywhere; it reads it from env, sends it as a Bearer header, 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