Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@harvest-forecast-mcp list my recent time entries"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
An MCP server for the Harvest and Forecast APIs — let AI agents like Claude track time, list projects, and manage assignments and scheduling.
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.
Related MCP server: harvest-mcp-server
# Run instantly without installing (recommended)
uvx harvest-forecast-mcp
# Or install with pip
pip install harvest-forecast-mcpThe 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 tools | Personal access token for the Harvest API |
| Harvest tools | Harvest account ID (numeric) |
| Forecast tools | Personal access token for the Forecast API |
| Forecast tools | Forecast account ID (numeric) |
| Yes | Identifying string for API requests (e.g. |
Tip: Harvest requires a descriptive
User-Agentheader. SetHARVEST_USER_AGENTto your app name and contact email.
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)"
}
}
}
}The server exposes 28 tools across the Harvest and Forecast APIs, including cross-API combinations:
Tool | Description |
| List all projects with client info, optionally filtered by active status |
| List all users, optionally filtered by active status |
| List all clients, optionally filtered by active status |
| List all tasks available for time tracking |
| List time entries filtered by user, project, and date range (defaults to last 30 days) |
| Log hours against a project + task with optional notes |
| List users assigned to a Harvest project with rates and budgets |
| Get the current authenticated Harvest user's identity and permissions |
Tool | Description |
| List all Forecast projects (for scheduling) |
| List all schedulable people with roles and teams |
| List all placeholders (role-based slots) |
| List all roles with their assigned people and placeholders |
| List all milestones across all projects |
| Get details for a single Forecast project by ID |
| Get details for a single Forecast person by ID |
| List scheduled assignments filtered by date range, project, or person |
| Schedule a person on a project with allocation and dates |
| Update an existing assignment |
| Delete an assignment |
| Get remaining budgeted hours for all projects |
| Get future scheduled hours from a date |
| Same, filtered to a single project |
| Get a mapping of project IDs to assigned person IDs |
| Scheduling load heatmap for a project |
| Scheduling load heatmap for a person |
| Scheduling load heatmap for a placeholder |
| Get current Forecast user identity and account IDs |
Tool | Description |
| A person's complete schedule: Forecast assignments + Harvest time entries for the period |
| Comprehensive project view: Harvest details + Forecast project + budget + recent time entries |
| Scheduled hours (Forecast) vs logged hours (Harvest) per person, with utilization % |
| Find people with capacity (not fully scheduled) in a date range |
| Summarize time entries grouped by project, user, or client |
| Budget burn-down: remaining budgeted hours vs logged hours last 30 days per project |
| Per-project scheduling overview: people, assignments, milestones for a date range |
# 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.
MIT
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.
Get a scheduling overview for all projects: assignments, assigned people, and milestones.
Combines Forecast assignments, people, and milestones into a per-project
view showing who is working on what during the date range.
Args:
start_date: Start of date range (YYYY-MM-DD).
end_date: End of date range (YYYY-MM-DD).
Inputs: end_date (required), start_date (required). Returns: result
Get budget burn-down: remaining budgeted hours (Forecast) vs logged hours (Harvest, last 30 days) per project.
Cross-references Forecast's remaining_budgeted_hours with recent Harvest
time entries to show which projects are burning through their budget fastest.
Inputs: no named parameters. Returns: result
Schedule a person on a Forecast project.
Args:
project_id: Forecast project ID (must be >= 1).
person_id: Forecast person ID (0 = Everyone).
start_date: Assignment start date (YYYY-MM-DD).
end_date: Assignment end date (YYYY-MM-DD).
allocation: Allocation in minutes per day (e.g. 480 = 8 hours).
notes: Optional notes for the assignment.
Inputs: end_date (required), person_id (required), project_id (required), start_date (required), +2 more. Returns: result
Log time against a Harvest project and task.
Args:
project_id: Harvest project ID.
task_id: Harvest task ID.
spent_date: Date the time was spent (YYYY-MM-DD).
hours: Number of hours to log (can be decimal, e.g. 1.5).
notes: Optional notes for the time entry.
Inputs: hours (required), task_id (required), project_id (required), spent_date (required), +1 more. Returns: result
Delete a Forecast assignment.
Args:
assignment_id: ID of the assignment to delete (must be >= 1).
Inputs: assignment_id (required). Returns: result
Get the current Forecast user's identity and account IDs.
Inputs: no named parameters. Returns: result
Get a mapping of Forecast project IDs to the person IDs assigned to each.
Args:
start_date: Start of date range (YYYY-MM-DD).
end_date: End of date range (YYYY-MM-DD).
Inputs: end_date (required), start_date (required). Returns: result
Get details for a single Forecast person by ID.
Args:
person_id: Forecast person ID.
Inputs: person_id (required). Returns: result
Get details for a single Forecast project by ID.
Args:
project_id: Forecast project ID.
Inputs: project_id (required). Returns: result
Get future scheduled hours for all projects starting from a date.
Args:
from_date: Starting date (YYYY-MM-DD).
Inputs: from_date (required). Returns: result
Get future scheduled hours for a specific Forecast project.
Args:
from_date: Starting date (YYYY-MM-DD).
project_id: Forecast project ID.
Inputs: from_date (required), project_id (required). Returns: result
Get a scheduling heatmap for a Forecast person.
Args:
person_id: Forecast person ID.
from_date: Start date (YYYY-MM-DD).
to_date: End date (YYYY-MM-DD).
scale: Time scale — "daily" or "weekly".
Inputs: to_date (required), from_date (required), person_id (required), scale. Returns: result
Get a scheduling heatmap for a Forecast placeholder.
Args:
placeholder_id: Forecast placeholder ID.
from_date: Start date (YYYY-MM-DD).
to_date: End date (YYYY-MM-DD).
scale: Time scale — "daily" or "weekly".
Inputs: to_date (required), from_date (required), placeholder_id (required), scale. Returns: result
Get a scheduling heatmap for a Forecast project.
Args:
project_id: Forecast project ID.
from_date: Start date (YYYY-MM-DD).
to_date: End date (YYYY-MM-DD).
scale: Time scale — "daily" or "weekly".
Inputs: to_date (required), from_date (required), project_id (required), scale. Returns: result
Get remaining budgeted hours for all Forecast projects.
Inputs: no named parameters. Returns: result
Get the current authenticated Harvest user's identity and permissions.
Inputs: no named parameters. Returns: result
List scheduled assignments in Forecast within a date range.
Args:
start_date: Start of date range (YYYY-MM-DD). Required.
end_date: End of date range (YYYY-MM-DD). Required.
project_id: Filter to assignments for a specific project.
person_id: Filter to assignments for a specific person.
Inputs: end_date (required), start_date (required), person_id, project_id. Returns: result
List all milestones across all Forecast projects.
Inputs: no named parameters. Returns: result
List all people being scheduled in Forecast, with their roles and teams.
Inputs: no named parameters. Returns: result
List all placeholders (unnamed/role-based slots) available for scheduling in Forecast.
Inputs: no named parameters. Returns: result
List all projects in Forecast (for scheduling purposes).
Inputs: no named parameters. Returns: result
List all roles defined in Forecast, with their assigned people and placeholders.
Inputs: no named parameters. Returns: result
List all clients in Harvest.
Args:
is_active: If True, only return active clients.
Inputs: is_active. Returns: result
List all projects in Harvest with client information.
Args:
is_active: If True, only return active projects. If False, only archived.
Inputs: is_active. Returns: result
List all tasks available for time tracking in Harvest.
Args:
is_active: If True, only return active tasks.
Inputs: is_active. Returns: result
List all users in Harvest.
Args:
is_active: If True, only return active users.
Inputs: is_active. Returns: result
List users assigned to a Harvest project with their rates and budgets.
Args:
project_id: Harvest project ID.
Inputs: project_id (required). Returns: result
List time entries from Harvest, optionally filtered by user, project, and date range.
Args:
user_id: Filter to a specific user's entries.
project_id: Filter to a specific project's entries.
from_date: Start date (YYYY-MM-DD). Defaults to 30 days ago.
to_date: End date (YYYY-MM-DD). Defaults to today.
Inputs: to_date, user_id, from_date, project_id. Returns: result
Get a person's complete schedule: Forecast assignments + Harvest time entries for the period.
Combines both APIs to show what a person is scheduled to work on (Forecast)
and what they've actually logged (Harvest) in one view.
Args:
person_id: Forecast person ID (for assignments) — also used to look up
the corresponding Harvest user if the person has a harvest_user_id.
start_date: Start of date range (YYYY-MM-DD).
end_date: End of date range (YYYY-MM-DD).
Inputs: end_date (required), person_id (required), start_date (required). Returns: result
Get a comprehensive project overview combining Harvest and Forecast data.
Returns Harvest project details, Forecast project details (if linked),
remaining budgeted hours, future scheduled hours, and recent time entries.
Args:
project_id: Harvest project ID.
Inputs: project_id (required). Returns: result
Get team utilization: scheduled hours (Forecast) vs logged hours (Harvest) per person.
For each Forecast person with a linked Harvest user, shows their total
scheduled allocation and total logged hours in the date range, with a
utilization percentage.
Args:
start_date: Start of date range (YYYY-MM-DD).
end_date: End of date range (YYYY-MM-DD).
Inputs: end_date (required), start_date (required). Returns: result
Summarize Harvest time entries, grouped by project, user, or client.
Args:
from_date: Start date (YYYY-MM-DD). Defaults to 7 days ago.
to_date: End date (YYYY-MM-DD). Defaults to today.
group_by: How to group the summary — "project", "user", or "client".
Inputs: to_date, group_by, from_date. Returns: result
Update an existing Forecast assignment.
Args:
assignment_id: ID of the assignment to update (must be >= 1).
project_id: Forecast project ID (must be >= 1).
person_id: Forecast person ID.
start_date: New start date (YYYY-MM-DD).
end_date: New end date (YYYY-MM-DD).
allocation: New allocation in minutes per day.
notes: New notes.
Inputs: end_date (required), person_id (required), project_id (required), start_date (required), +3 more. Returns: result
Find people who have capacity (are not fully scheduled) in a date range.
Lists Forecast people whose total scheduled allocation in the period
is below the given threshold, so they can take on more work.
Args:
start_date: Start of date range (YYYY-MM-DD).
end_date: End of date range (YYYY-MM-DD).
max_daily_minutes: Max allocation to be considered "available" (default 480 = 8h/day).
Inputs: end_date (required), start_date (required), max_daily_minutes. Returns: result
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 34 tools
Each tool targets a distinct resource or action, with clear separation between Forecast and Harvest operations. Overlaps like person_schedule vs get_person_heatmap are differentiated by purpose (combined view vs scheduling heatmap). No tools are redundant or confusing.
Tools predominantly follow a consistent verb_noun pattern (e.g., create_assignment, list_forecast_people). Exceptions like all_projects_schedule and who_is_available are still descriptive and follow a logical naming scheme. No mixed casing or erratic patterns.
With 34 tools, the set is comprehensive but slightly above average. However, given the dual-API coverage (Harvest and Forecast) and the inclusion of cross-reference tools, the count is justified and not excessive. Each tool serves a clear purpose.
The tool surface covers core CRUD for assignments and time entry creation, plus comprehensive listing and cross-referencing. Minor gaps exist (no time entry update/delete, no Harvest project creation), but these are likely out of scope for a scheduling/time-tracking integration server.
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
One MCP server for the services your AI needs: memory, files, Microsoft 365, kanban and more.
MCP server for AI agents to plan, verify, and deploy Cloudflare-native apps.
