# 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

| Tool | Description |
|---|---|
| `get_me` | Current authenticated user |
| `list_organizations` | All orgs you belong to |
| `list_members` | Members in an organization |
| `list_projects` | Projects in an organization |
| `list_time_entries` | Time entries (filter by user/project/date) |
| `get_daily_activities` | Daily activity % (keyboard/mouse) |
| `list_screenshots` | Screenshot metadata + image URLs |
| `get_weekly_report` | Weekly team summary |
| `get_report_by_member` | Custom report by team member |
| `get_report_by_project` | Custom report by project |
| `list_tasks` | Tasks in org/project |
| `list_payments` | Payment records |

## Setup

### 1. Get a Personal Access Token

Go to [developer.hubstaff.com/personal_access_tokens](https://developer.hubstaff.com/personal_access_tokens) and generate a PAT.

### 2. Install

```bash
# 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

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

### 4. Add to Claude Code

Add to `~/.claude/settings.json`:

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

Or if installed globally via npm:

```json
{
  "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