harvest-forecast-mcp

An MCP server for the Harvest and Forecast APIs — let AI agents like Claude track time, list projects, and manage assignments and scheduling.

What it does

harvest-forecast-mcp exposes Harvest (time tracking) and Forecast (resource scheduling) operations as Model Context Protocol tools. Once configured, an AI agent can:

• Track time — list, create, and delete time entries in Harvest
• Browse projects — list projects, clients, tasks, and users
• Manage scheduling — list and create Forecast assignments, milestones, and holidays

The server speaks stdio MCP, so it drops cleanly into Claude Desktop, Claude Code, or any MCP-compatible client.

Installation

# Run instantly without installing (recommended)
uvx harvest-forecast-mcp

# Or install with pip
pip install harvest-forecast-mcp

Configuration

The server reads credentials from environment variables. Harvest and Forecast use separate access tokens and account IDs, so you can configure one or both depending on which tools you need.

Variable	Required	Description
HARVEST_ACCESS_TOKEN	Harvest tools	Personal access token for the Harvest API
HARVEST_ACCOUNT_ID	Harvest tools	Harvest account ID (numeric)
FORECAST_ACCESS_TOKEN	Forecast tools	Personal access token for the Forecast API
FORECAST_ACCOUNT_ID	Forecast tools	Forecast account ID (numeric)
HARVEST_USER_AGENT	Yes	Identifying string for API requests (e.g. your-app (you@example.com))

Tip: Harvest requires a descriptive User-Agent header. Set HARVEST_USER_AGENT to your app name and contact email.

Claude Desktop configuration

Add the server to your claude_desktop_config.json:

{
  "mcpServers": {
    "harvest-forecast": {
      "command": "uvx",
      "args": ["harvest-forecast-mcp"],
      "env": {
        "HARVEST_ACCESS_TOKEN": "your-harvest-token",
        "HARVEST_ACCOUNT_ID": "123456",
        "FORECAST_ACCESS_TOKEN": "your-forecast-token",
        "FORECAST_ACCOUNT_ID": "123456",
        "HARVEST_USER_AGENT": "my-claude-agent (you@example.com)"
      }
    }
  }
}

Tools

The server exposes 28 tools across the Harvest and Forecast APIs, including cross-API combinations:

Harvest — time tracking & project management

Tool	Description
list_harvest_projects	List all projects with client info, optionally filtered by active status
list_harvest_users	List all users, optionally filtered by active status
list_harvest_clients	List all clients, optionally filtered by active status
list_harvest_tasks	List all tasks available for time tracking
list_time_entries	List time entries filtered by user, project, and date range (defaults to last 30 days)
create_time_entry	Log hours against a project + task with optional notes
list_project_assignments	List users assigned to a Harvest project with rates and budgets
harvest_whoami	Get the current authenticated Harvest user's identity and permissions

Forecast — scheduling & staffing

Tool	Description
list_forecast_projects	List all Forecast projects (for scheduling)
list_forecast_people	List all schedulable people with roles and teams
list_forecast_placeholders	List all placeholders (role-based slots)
list_forecast_roles	List all roles with their assigned people and placeholders
list_forecast_milestones	List all milestones across all projects
get_forecast_project	Get details for a single Forecast project by ID
get_forecast_person	Get details for a single Forecast person by ID
list_assignments	List scheduled assignments filtered by date range, project, or person
create_assignment	Schedule a person on a project with allocation and dates
update_assignment	Update an existing assignment
delete_assignment	Delete an assignment
get_remaining_budgeted_hours	Get remaining budgeted hours for all projects
get_future_scheduled_hours	Get future scheduled hours from a date
get_future_scheduled_hours_for_project	Same, filtered to a single project
get_assigned_people	Get a mapping of project IDs to assigned person IDs
get_project_heatmap	Scheduling load heatmap for a project
get_person_heatmap	Scheduling load heatmap for a person
get_placeholder_heatmap	Scheduling load heatmap for a placeholder
forecast_whoami	Get current Forecast user identity and account IDs

Cross-API — manager insights

Tool	Description
person_schedule	A person's complete schedule: Forecast assignments + Harvest time entries for the period
project_overview	Comprehensive project view: Harvest details + Forecast project + budget + recent time entries
team_utilization	Scheduled hours (Forecast) vs logged hours (Harvest) per person, with utilization %
who_is_available	Find people with capacity (not fully scheduled) in a date range
time_summary	Summarize time entries grouped by project, user, or client
budget_status	Budget burn-down: remaining budgeted hours vs logged hours last 30 days per project
all_projects_schedule	Per-project scheduling overview: people, assignments, milestones for a date range

Development

# Install dependencies
uv sync --group dev

# Run tests
uv run pytest

# Type check
uv run pyright src/harvest_forecast_mcp

# Lint
uv run ruff check .

# Format
uv run ruff format .

See CONTRIBUTING.md for full development guidelines.

License

MIT

Disclaimer

This project is unofficial and not affiliated with, endorsed by, or sponsored by Harvest Inc. or its subsidiaries. "Harvest" and "Forecast" are trademarks of their respective owners. This software is provided "as-is", without any warranty express or implied.

MIT — Copyright (c) 2025 AZX, PBC.