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

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