@standardbeagle/harvest-mcp

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

• Copy the environment template:

cp .env.example .env

• 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