Harvest MCP Server

A Model Context Protocol (MCP) server that provides integration with the Harvest API v2.

Features

This MCP server provides tools for interacting with Harvest time tracking data:

Time Entry Management

• List time entries with filters
• Create new time entries
• Update existing time entries
• Delete time entries

Project & Task Management

• List and view projects
• List available tasks

User & Client Management

• Get current user information
• List all users
• List all clients

Reporting

• Generate time reports for date ranges

Assignments

• List project assignments
• List task assignments for projects

Installation

# Clone the repository
git clone <repository-url>
cd harvest-mcp

# Install dependencies
npm install

# Build the project
npm run build

Configuration

1. Copy the environment template:

cp .env.example .env

2. Edit .env and add your Harvest credentials:

HARVEST_ACCOUNT_ID=your_account_id
HARVEST_ACCESS_TOKEN=your_access_token

To get your Harvest credentials:

• Log in to your Harvest account
• Go to Developers
• Create a new personal access token
• Note your Account ID

Development

# Run in development mode with hot reload
npm run dev

# Build the project
npm run build

# Run the built server
npm start

Testing

The project includes comprehensive tests to verify integration with the Harvest API:

# Run unit tests
npm test

# Run unit tests in watch mode
npm run test:watch

# Run integration tests (requires valid .env setup)
npm run test:integration

Integration Tests

The integration tests connect to your actual Harvest account and perform read-only operations to verify the MCP server works correctly. These tests:

• Connect to the MCP server via stdio transport
• Test all 14 available tools
• Verify proper data structure responses
• Test error handling for invalid inputs
• Use actual Harvest API data (read-only operations only)

Requirements for integration tests:

• Valid .env file with HARVEST_ACCOUNT_ID and HARVEST_ACCESS_TOKEN
• Active Harvest account with some data (projects, time entries, etc.)
• Network access to Harvest API

Using with Claude Desktop

Add the following to your Claude Desktop configuration file:

{
  "mcpServers": {
    "harvest": {
      "command": "node",
      "args": ["/path/to/harvest-mcp/dist/index.js"],
      "env": {
        "HARVEST_ACCOUNT_ID": "your_account_id",
        "HARVEST_ACCESS_TOKEN": "your_access_token"
      }
    }
  }
}

Available Tools

| Tool | Description | |------|-------------| | harvest_list_time_entries | List time entries with optional filters | | harvest_create_time_entry | Create a new time entry | | harvest_update_time_entry | Update an existing time entry | | harvest_delete_time_entry | Delete a time entry | | harvest_restart_timer | Restart a stopped time entry timer | | harvest_stop_timer | Stop a running time entry timer | | harvest_list_projects | List all projects | | harvest_get_project | Get details of a specific project | | harvest_list_tasks | List all tasks | | harvest_get_current_user | Get information about the authenticated user | | harvest_list_users | List all users in the account | | harvest_list_clients | List all clients | | harvest_time_report | Get time report for a date range | | harvest_list_project_assignments | List project assignments for the current user | | harvest_list_task_assignments | List task assignments for a project |

Tool Parameters

Time Entry Tools

harvest_list_time_entries

• user_id (string): Filter by user ID
• project_id (string): Filter by project ID
• from (string): Start date (YYYY-MM-DD)
• to (string): End date (YYYY-MM-DD)
• page (number): Page number
• per_page (number): Results per page (max 100)

harvest_create_time_entry

• project_id (string, required): Project ID
• task_id (string, required): Task ID
• spent_date (string, required): Date of the entry (YYYY-MM-DD)
• hours (number): Hours worked
• notes (string): Notes for the time entry

License

MIT