Install
You don't install the Hoursmith MCP server by hand — your AI client launches it with npx. Here's the run command and environment variables.
There's nothing to install by hand. MCP clients spawn the Hoursmith server on demand with npx, so
you simply add a config block to your client and it pulls the latest version when it starts.
- Plan
- StudioAgency
You need Node.js 18+ and an hsk_ API token before the server will run.
The run command
Every MCP client launches the server the same way — with npx, over stdio:
npx -y @hoursmith/mcp-serverThe -y flag tells npx to download and run the package without an interactive prompt. The binary
name is hoursmith-mcp.
You don't usually run this command yourself — your MCP client does, using the config you add in the
next steps. Running it directly is mostly useful as a sanity check that Node and npx work.
Environment variables
The server is configured entirely through environment variables, which you set in your client's config:
| Variable | Required | Default | Description |
|---|---|---|---|
HOURSMITH_API_TOKEN | Yes | — | The Bearer token from Settings → API. Must start with hsk_. |
HOURSMITH_API_URL | No | https://hoursmith.app | Override the API base URL for self-hosted or staging instances. |
HOURSMITH_MCP_CLIENT | No | hoursmith-mcp | A label identifying the calling client, sent as a User-Agent suffix. |
Most users only ever set HOURSMITH_API_TOKEN. Leave HOURSMITH_API_URL alone unless you're
pointing at a self-hosted or staging Hoursmith.
Configure your client
Pick your tool and follow its setup guide:
Claude Desktop
macOS and Windows config file paths.
Cursor
Add the server in ~/.cursor/mcp.json.
Other clients
Zed and any stdio-capable MCP client.