hubstaff-mcp

A Model Context Protocol (MCP) server for Hubstaff. Operate your Hubstaff organizations, projects, tasks, members, tracked-time activities and timesheets through any MCP-compatible LLM client. Read your timesheet, log time, and inspect your team in natural language.

Built on FastMCP and scaffolded from the-momentum/python-ai-kit.

Connect it to your LLM

You need two things: a Hubstaff Personal Access Token, and one config entry in your client. No clone required: uv runs the server straight from GitHub.

1. Get a Personal Access Token at developer.hubstaff.com/account/personal-access-tokens. That's the value of HUBSTAFF_PERSONAL_ACCESS_TOKEN in the steps below.

2. Add the server to your client:

Claude Code

claude mcp add hubstaff \
  -e HUBSTAFF_PERSONAL_ACCESS_TOKEN=your_pat_here \
  -- uvx --from git+https://github.com/farce1/hubstify-mcp.git hubstaff-mcp

claude mcp list should then show hubstaff connected. Add -s user to enable it across all your projects.

Claude Desktop / Claude Cowork

Edit claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\). Cowork shares the same desktop MCP configuration:

{
  "mcpServers": {
    "hubstaff": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/farce1/hubstify-mcp.git", "hubstaff-mcp"],
      "env": { "HUBSTAFF_PERSONAL_ACCESS_TOKEN": "your_pat_here" }
    }
  }
}

Restart the app afterward.

Cursor

Create .cursor/mcp.json in your project (or ~/.cursor/mcp.json for all projects) with the same mcpServers block shown above for Claude Desktop.

Codex

Add to ~/.codex/config.toml:

[mcp_servers.hubstaff]
command = "uvx"
args = ["--from", "git+https://github.com/farce1/hubstify-mcp.git", "hubstaff-mcp"]
env = { HUBSTAFF_PERSONAL_ACCESS_TOKEN = "your_pat_here" }

Prefer a local clone? After git clone … && uv sync, replace the launch command everywhere above with uv --directory /absolute/path/to/hubstify-mcp run hubstaff-mcp.

3. Try it. Ask your assistant:

• "Who am I on Hubstaff?" → get_current_user

• "Show my tracked time this week." → get_tracked_time

• "Give me my timesheet summary for last month." → get_timesheet

• "What projects and tasks am I assigned to?" → get_projects + get_tasks

• "Log 2 hours to project Acme today with note 'API integration'." → log_time

Related MCP server: timedoctor-mcp

Tools

Hubstaff v2 limitation: time entries are create-only. The v2 API has no endpoint to edit or delete a tracked-time entry, so this server intentionally does not expose update/delete tools; do that in the Hubstaff web app. Tracked time is read via daily activities.

Highlights

• 🔑 PAT auth with automatic access-token refresh and rotation handling (the rotated refresh token is persisted; the token endpoint's 5/hour limit is respected)

• ⏱️ Read tracked time and per-project timesheets over natural periods ("this week", "last month", …)

• ✍️ Log manual time entries and create tasks

• 🛡️ Rate-limit aware (honors Retry-After, backs off on 5xx) with cursor pagination

• 🧰 A guarded read-only escape hatch for endpoints without a dedicated tool

Other ways to install

The config above needs no clone, but the same hubstaff-mcp command is available via:

uv tool install git+https://github.com/farce1/hubstify-mcp.git   # persistent, on PATH
pipx run --spec git+https://github.com/farce1/hubstify-mcp.git hubstaff-mcp   # pipx
pip install git+https://github.com/farce1/hubstify-mcp.git       # into a venv

# From source (development):
git clone https://github.com/farce1/hubstify-mcp.git && cd hubstify-mcp && uv sync

Environment variables

Hubstaff rotates the refresh token on every exchange; this server persists the newest token (mode 0600) so it survives restarts. If you revoke the token, update HUBSTAFF_PERSONAL_ACCESS_TOKEN and delete the token store file.

Troubleshooting

• HUBSTAFF_PERSONAL_ACCESS_TOKEN is not set: the env var didn't reach the server; check the env block in your client config.

• Auth errors after it worked before: the token may have been revoked or rotated out of band. Update HUBSTAFF_PERSONAL_ACCESS_TOKEN and delete ~/.hubstaff-mcp/tokens.json.

• Wrong day for "today"/"this week": the server uses your Hubstaff account's timezone; check it under your Hubstaff profile settings.

Self-hosting over HTTP

By default the server talks stdio (the client spawns it as a subprocess). To run it as a long-lived HTTP service instead, set MCP_TRANSPORT=http:

HUBSTAFF_PERSONAL_ACCESS_TOKEN=your_pat MCP_TRANSPORT=http MCP_PORT=8000 \
  uvx --from git+https://github.com/farce1/hubstify-mcp.git hubstaff-mcp

The endpoint is then http://<host>:<port>/mcp, which any HTTP-capable MCP client can connect to.

⚠️ Single-user only. The server acts as the one identity behind HUBSTAFF_PERSONAL_ACCESS_TOKEN; every request reads and writes that account's Hubstaff data. Do not expose this endpoint to other people or the public internet; keep it bound to localhost or your private network and put your own authentication in front of it. Multi-tenant hosting (each user with their own Hubstaff token) is not yet supported.

Development

make install     # uv sync --all-groups
make test        # pytest
make lint        # ruff check
make typecheck   # ty check
make check       # lint + typecheck + tests + format check

Architecture

A thin, layered design (each layer has one responsibility):

app/
├── domain/        # Pydantic models + value objects (Duration, DateRange)
├── hubstaff/      # auth (token rotation) + HTTP client (retry, pagination)
├── repositories/  # one per aggregate: endpoints + envelope -> domain models
├── services/      # use-case logic (date normalization, timesheet projection)
└── mcp/           # FastMCP tools (thin adapters) + composition root

License

MIT. See LICENSE.