Harvest MCP Server

A Model Context Protocol (MCP) server that integrates with Harvest time tracking. This server allows AI assistants to interact with your Harvest account to log time, view projects, manage tasks, and track your work hours.

When combined with an Azure DevOps (ADO) MCP server and the included example skill, your AI assistant can automatically review ADO work items for effort-hours changes and log the corresponding time to Harvest.

Features

• List active projects and their details
• View tasks for specific projects
• Log time entries with notes
• View today's time entries and total hours
• Start and stop timers
• Update existing time entries
• Docker support for easy deployment

Prerequisites

• Node.js 20 or higher (for local development)
• Docker and Docker Compose (for containerized deployment, optional)
• Harvest account with API access
• Harvest Personal Access Token (PAT) — Get one here
• Azure DevOps (ADO) MCP server — required if you want to use the time-logging skill that reads work items from ADO (see ADO MCP Server below)

Quick Start — Setting Up in Cursor

1. Get Your Harvest Credentials

1. Go to https://id.getharvest.com/developers
2. Create a new Personal Access Token
3. Note your Account ID and Access Token

2. Set Environment Variables

The server expects your Harvest credentials to be available as OS-level environment variables. Set these in your system:

Windows (PowerShell — persistent for your user):

[System.Environment]::SetEnvironmentVariable("Harvest_ID", "your_account_id", "User")
[System.Environment]::SetEnvironmentVariable("Harvest_Token", "your_access_token", "User")

macOS / Linux (add to `~/.bashrc`, `~/.zshrc`, or equivalent):

export Harvest_ID="your_account_id"
export Harvest_Token="your_access_token"

After setting them, restart your terminal (and Cursor) so the new variables are picked up.

3. Build the Server

Clone this repo and build:

git clone <repo-url>
cd HarvestMCP
npm install
npm run build

4. Add the MCP Server to Cursor

In your Cursor settings, open (or create) your MCP configuration file. On Windows this is typically at:

%USERPROFILE%\.cursor\mcp.json

Add the Harvest server entry. A sample is provided in examplemcp.json.md:

{
  "mcpServers": {
    "harvest": {
      "type": "stdio",
      "command": "node",
      "args": [
        "C:\\path\\to\\HarvestMCP\\build\\index.js"
      ],
      "env": {
        "HARVEST_ACCOUNT_ID": "${env:Harvest_ID}",
        "HARVEST_ACCESS_TOKEN": "${env:Harvest_Token}"
      }
    }
  }
}

Important: Update the path in args to the absolute path of build/index.js on your machine.

The ${env:...} syntax tells Cursor to read the values from your OS environment variables at runtime. This avoids committing secrets to your config files.

5. (Optional) Install the Example Skill

An example Cursor agent skill is provided in example-skill.md. This skill teaches the AI assistant how to review ADO work items for effort-hours changes and log the corresponding time to Harvest.

To use it:

1. Copy example-skill.md to your Cursor skills directory (e.g. ~/.cursor/skills/log-harvest-time/SKILL.md)
2. Adjust the skill metadata (name, description) if needed
3. The skill will then be available to your Cursor agent when you ask it to "log time", "log hours", or "submit timesheet"

Note: This skill requires both the Harvest MCP server (this project) and an ADO MCP server to be configured in Cursor. Without the ADO MCP server, the skill cannot read work item effort-hours.

ADO MCP Server

The example time-logging skill relies on an Azure DevOps MCP server to query work items and detect effort-hours changes. You need to have a separate ADO MCP server configured in your Cursor MCP settings alongside this Harvest server.

Your Cursor mcp.json should contain entries for both servers, for example:

{
  "mcpServers": {
    "harvest": {
      // ... Harvest config as shown above ...
    },
    "ado": {
      // ... your ADO MCP server config ...
    }
  }
}

Refer to your ADO MCP server's documentation for its specific setup instructions and required environment variables (e.g. ADO PAT, organization URL, etc.).

Included Examples

Alternative Setup — VS Code

This repo also includes a .vscode/mcp.json for running the server as a VS Code MCP server. The same environment variable approach applies — set Harvest_ID and Harvest_Token as OS environment variables, and VS Code will inject them at runtime via the ${env:...} syntax.

Installation Options

Option A: Local Development

Install dependencies and build:

npm install
npm run build

Run the server directly (outside of an MCP client):

npm start

If you run it directly, you must provide HARVEST_ACCOUNT_ID and HARVEST_ACCESS_TOKEN in your shell environment.

Option B: Docker Container

Build and run with Docker Compose:

docker-compose up -d

Docker Compose reads HARVEST_ACCOUNT_ID / HARVEST_ACCESS_TOKEN from your shell environment. It will also read a .env file next to docker-compose.yml if you choose to use one.

Or build manually:

docker build -t harvest-mcp-server .
docker run -e HARVEST_ACCOUNT_ID=your_id -e HARVEST_ACCESS_TOKEN=your_token harvest-mcp-server

Available Tools

The server exposes the following tools to MCP clients:

list_projects

Lists all active projects in your Harvest account.

Example: "Show me my active projects"

list_project_tasks

Lists all tasks for a specific project.

Parameters:

• project_id (number): The ID of the project

Example: "What tasks are available for project 12345?"

log_time

Logs a time entry to Harvest.

Parameters:

• project_id (number): The ID of the project
• task_id (number): The ID of the task
• hours (number): Number of hours to log
• spent_date (string, optional): Date in YYYY-MM-DD format (defaults to today)
• notes (string, optional): Notes about the work

Example: "Log 2.5 hours to project 12345, task 67890 with notes 'Developed new feature'"

get_todays_time

Retrieves all time entries for today with total hours.

Example: "How much time have I logged today?"

start_timer

Starts a running timer for a project and task.

Parameters:

• project_id (number): The ID of the project
• task_id (number): The ID of the task
• notes (string, optional): Notes about what you're working on

Example: "Start a timer for project 12345, task 67890"

stop_timer

Stops a running timer.

Parameters:

• time_entry_id (number): The ID of the time entry to stop

Example: "Stop timer 98765"

update_time_entry

Updates an existing time entry (hours, notes, project, task, or date).

Parameters:

• time_entry_id (number): The ID of the time entry to update
• hours (number, optional): New number of hours
• notes (string, optional): Updated notes
• project_id (number, optional): New project ID
• task_id (number, optional): New task ID
• spent_date (string, optional): New date in YYYY-MM-DD format

Example: "Update time entry 98765 to 3 hours"

Using with Claude Desktop

To use this MCP server with Claude Desktop, add it to your configuration file:

macOS/Linux: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "harvest": {
      "command": "node",
      "args": ["/absolute/path/to/HarvestMCP/build/index.js"],
      "env": {
        "HARVEST_ACCOUNT_ID": "your_account_id",
        "HARVEST_ACCESS_TOKEN": "your_access_token"
      }
    }
  }
}

Development

Build

npm run build

Watch mode (auto-rebuild on changes)

npm run watch

Troubleshooting

"HARVEST_ACCOUNT_ID and HARVEST_ACCESS_TOKEN must be set"

Make sure the environment variables Harvest_ID and Harvest_Token are set at the OS level and that you have restarted Cursor / your terminal after setting them. The MCP config uses ${env:Harvest_ID} and ${env:Harvest_Token} to inject these at runtime.

"Error fetching projects: 401"

Your access token may be invalid or expired. Generate a new one from the Harvest developers page.

"Error fetching projects: 403"

Harvest returns 403 Forbidden when your token doesn't have permission for an endpoint. This server uses /v2/users/me/project_assignments to list projects and tasks you're assigned to, which works for normal member accounts. If you still get 403:

• Double-check HARVEST_ACCOUNT_ID matches the account for your token.
• Confirm the token hasn't been revoked.
• Verify you're assigned to at least one project in Harvest.

Docker container not starting

Check the logs:

docker-compose logs harvest-mcp

Ensure HARVEST_ACCOUNT_ID / HARVEST_ACCESS_TOKEN are available to Docker Compose (either in your shell environment or via a .env file next to docker-compose.yml).

Security Notes

• Never commit secrets (tokens, PATs) to git
• The Harvest access token provides full access to your Harvest account
• Consider using environment-specific tokens for different deployments
• Regularly rotate your access tokens
• The ${env:...} syntax in MCP configs keeps secrets out of config files

API Rate Limits

Harvest API has rate limits:

• 100 requests per 15 seconds per access token
• This server includes no built-in rate limiting

License

MIT

Resources

• Harvest API Documentation
• Harvest Developers — Personal Access Tokens
• Model Context Protocol
• MCP TypeScript SDK