hubstaff-mcp

MCP server for the Hubstaff v2 API. Gives Claude Code (or any MCP client) native access to team time tracking, activities, screenshots, and reports.

Tools

Setup

1. Get a Personal Access Token

Go to developer.hubstaff.com/personal_access_tokens and generate a PAT.

2. Install

# Clone
git clone https://github.com/MerlinoMarketing/hubstaff-mcp.git
cd hubstaff-mcp
npm install

# Or via npx (after npm publish)
npx hubstaff-mcp

3. Configure

cp .env.example .env
# Edit .env and paste your PAT

4. Add to Claude Code

Add to ~/.claude/settings.json:

{
  "mcpServers": {
    "hubstaff": {
      "command": "node",
      "args": ["/path/to/hubstaff-mcp/index.js"]
    }
  }
}

Or if installed globally via npm:

{
  "mcpServers": {
    "hubstaff": {
      "command": "npx",
      "args": ["hubstaff-mcp"]
    }
  }
}

Auth

The PAT is actually a refresh token (90-day expiry). The server automatically:

• Exchanges the PAT for an access token on first request

• Caches the access token (24hr TTL)

• Auto-refreshes on 401 errors

Rate Limits

Hubstaff allows 1,000 requests/hour per application. The server uses cursor-based pagination (page_start_id) for large result sets.

License

MIT