Hubstaff MCP Server

A Model Context Protocol (MCP) server for Hubstaff API integration, enabling seamless time tracking, project management, and team collaboration through AI assistants.

Features

• Time Tracking: Create, update, and retrieve time entries

• Project Management: List and manage projects, tasks, and teams

• User Management: Get user information and organization details

• Activity Monitoring: Access screenshots, activities, and productivity data

• Reporting: Generate timesheets and activity reports

Related MCP server: TimeCamp MCP Server

Installation

Using uv (recommended)

uv add hubstaff-mcp

Using pip

pip install hubstaff-mcp

Configuration

Before using the server, you need to obtain a Personal Access Token from Hubstaff:

1. Log in to your Hubstaff account

2. Go to Settings → Personal Access Tokens

3. Create a new token with the required permissions

Environment Variables

Set the following environment variable:

export HUBSTAFF_REFRESH_TOKEN="your_personal_access_token_here"

Or create a .env file in your project root:

HUBSTAFF_REFRESH_TOKEN=your_personal_access_token_here

Note: The personal access token is used as a refresh token to obtain temporary access tokens for API calls. This approach provides better security by automatically handling token renewal.

Usage

Running the Server

hubstaff-mcp

Or using uv:

uv run hubstaff-mcp

Configuration with Claude Desktop

Add the following to your Claude Desktop configuration file (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

Option 1: Using the installed package (Recommended)

{
  "mcpServers": {
    "hubstaff": {
      "command": "hubstaff-mcp",
      "env": {
        "HUBSTAFF_REFRESH_TOKEN": "your_personal_access_token_here"
      }
    }
  }
}

Option 2: Using uv with project directory

{
  "mcpServers": {
    "hubstaff": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/your/project",
        "run",
        "hubstaff-mcp"
      ],
      "env": {
        "HUBSTAFF_REFRESH_TOKEN": "your_personal_access_token_here"
      }
    }
  }
}

Option 3: Using uv run directly

{
  "mcpServers": {
    "hubstaff": {
      "command": "uv",
      "args": ["run", "hubstaff-mcp"],
      "env": {
        "HUBSTAFF_REFRESH_TOKEN": "your_personal_access_token_here"
      }
    }
  }
}

Available Tools

The server provides the following tools:

Time Management

• get_time_entries - Retrieve time entries with filtering options

• create_time_entry - Create a new time entry

• update_time_entry - Update an existing time entry

• delete_time_entry - Delete a time entry

Project & Task Management

• get_projects - List all projects

• get_project_details - Get detailed project information

• get_tasks - List tasks for a project

• create_task - Create a new task

• update_task - Update task details

User & Organization

• get_current_user - Get current user information

• get_users - List organization users

• get_organizations - List user organizations

• get_teams - List organization teams

Activity & Monitoring

• get_activities - Retrieve user activities

• get_screenshots - Get screenshots for time entries

• get_timesheets - Generate timesheets

Example Queries

Once configured with Claude Desktop, you can ask:

• "Show me my time entries for this week"

• "Create a new task called 'Update documentation' in the Development project"

• "What projects am I currently working on?"

• "Get my team's activity summary for today"

• "Show me screenshots from my last work session"

Development

Setup

git clone https://github.com/yourusername/hubstaff-mcp
cd hubstaff-mcp
uv sync --dev

Running Tests

uv run pytest

Code Formatting

uv run black .
uv run ruff check .

API Coverage

This MCP server covers the following Hubstaff API endpoints:

• Time Entries

• Projects & Tasks

• Users & Organizations

• Teams

• Activities & Screenshots

• Timesheets

• Notes

Contributing

1. Fork the repository

2. Create a feature branch

3. Make your changes

4. Add tests for new functionality

5. Run the test suite

6. Submit a pull request

License

MIT License - see LICENSE file for details.

Support

For issues and questions:

• GitHub Issues: https://github.com/yourusername/hubstaff-mcp/issues

• Hubstaff API Documentation: https://developer.hubstaff.com/docs/hubstaff_v2