Hubstaff MCP Server (TypeScript)

A Model Context Protocol (MCP) server for integrating with Hubstaff Time Tracking (API v2) and Hubstaff Tasks (API v1).

Setup

Installation

npm install
npm run build

Environment Variables

Set one of the following authentication options:

# Option 1: Direct access token
export HUBSTAFF_ACCESS_TOKEN="your_access_token"

# Option 2: Refresh token (auto-refreshes)
export HUBSTAFF_REFRESH_TOKEN="your_refresh_token"

Running the Server

npm start

Or in development mode:

npm run dev

Tools

Users (1 tool)

• hubstaff_get_current_user - Get current user information

Organizations (2 tools)

• hubstaff_list_organizations - List all organizations
• hubstaff_list_org_members - List organization members with pagination

Projects (3 tools)

• hubstaff_list_projects - List projects with filtering and pagination
• hubstaff_create_project - Create a new project
• hubstaff_update_project - Update existing project

Activities (2 tools)

• hubstaff_list_activities - List tracked activities with filters
• hubstaff_list_daily_activities - List aggregated daily activities

Screenshots (1 tool)

• hubstaff_list_screenshots - List screenshots from tracked time

Notes (1 tool)

• hubstaff_list_notes - List notes from tracked time

App/URL Usage (2 tools)

• hubstaff_list_app_usage - List application usage during tracked time
• hubstaff_list_url_usage - List URL usage during tracked time

Tasks - Time Tracking API v2 (3 tools)

• hubstaff_list_tasks - List tasks with filtering
• hubstaff_get_task - Get specific task details
• hubstaff_create_task - Create a new task

Reports (1 tool)

• hubstaff_weekly_report - Generate weekly activity report

Board Tasks - Tasks API v1 (8 tools)

• hubstaff_tasks_list_projects - List task board projects
• hubstaff_tasks_list_columns - List project columns
• hubstaff_tasks_list_tasks - List tasks in project
• hubstaff_tasks_get_task - Get task details
• hubstaff_tasks_create_task - Create board task
• hubstaff_tasks_update_task - Update board task
• hubstaff_tasks_delete_task - Delete board task
• hubstaff_tasks_list_sprints - List project sprints

Webhooks (2 tools)

• hubstaff_list_webhooks - List configured webhooks
• hubstaff_create_webhook - Create new webhook

Features

Authentication

• Automatic token refresh 60 seconds before expiry
• Support for both access tokens and refresh tokens
• Secure token caching

Response Formats

All tools support both json and markdown response formats:

• response_format: "json" - Returns structured JSON
• response_format: "markdown" - Returns formatted markdown (default)

Pagination

List tools support pagination with:

• page_start_id - ID to start from
• page_limit - Number of items (max 100)
• has_more - Indicates more results available
• next_page_start_id - ID for next page

Error Handling

• 401: Authentication failed
• 403: Permission denied
• 404: Resource not found
• 429: Rate limit exceeded (1000 req/hr)
• Timeout: 30 second request timeout

Architecture

src/
├── index.ts          # Main server entry with tool registration
├── client.ts         # TokenManager and HTTP client
├── constants.ts      # API URLs and configuration
├── types.ts          # TypeScript interfaces
└── tools/
    ├── users.ts
    ├── organizations.ts
    ├── projects.ts
    ├── activities.ts
    ├── screenshots.ts
    ├── notes.ts
    ├── usage.ts
    ├── tasks.ts
    ├── reports.ts
    ├── board-tasks.ts
    └── webhooks.ts

Development

TypeScript

• Strict mode enabled
• Full type safety
• ESM modules

Validation

• Zod schemas with .strict() enforcement
• Input validation on all parameters

Testing

To test locally, you can use the MCP Inspector:

npm run build
npx @modelcontextprotocol/inspector ./dist/index.js

API References

• Hubstaff Time Tracking API v2: https://api.hubstaff.com/v2
• Hubstaff Tasks API v1: https://api.hubstaff.com/v1
• Auth: https://account.hubstaff.com/access_tokens