@mnicole-dev/harvest-mcp-server

A Model Context Protocol (MCP) server for the Harvest time tracking API (v2). Manage time entries, projects, tasks, clients, users, and timers from any MCP-compatible client.

Features

37 tools covering the full Harvest API v2:

Time Entries (8 tools)

| Tool | Description | |------|-------------| | list-time-entries | List entries with filters (date range, project, user, task, billed, running) | | get-time-entry | Get a single time entry by ID | | create-time-entry | Log hours for a project/task on a date (duration or start/end time) | | update-time-entry | Update hours, notes, date, project, or task | | delete-time-entry | Delete a time entry | | start-timer | Start a running timer for a project/task | | stop-timer | Stop a running timer | | restart-timer | Restart a stopped timer |

Projects (4 tools)

| Tool | Description | |------|-------------| | list-projects | List all projects (filter by client, active status) | | get-project | Get project details (budget, rates, dates, notes) | | create-project | Create a project with billing, budget, and fee settings | | update-project | Update project settings | | delete-project | Delete a project |

Tasks (4 tools)

| Tool | Description | |------|-------------| | list-tasks | List all tasks in the account | | create-task | Create a new task | | update-task | Update a task | | delete-task | Delete a task |

Task Assignments (4 tools)

| Tool | Description | |------|-------------| | list-project-task-assignments | List which tasks are assigned to a project | | create-task-assignment | Assign a task to a project | | update-task-assignment | Update task assignment (billable, rate, budget) | | delete-task-assignment | Remove a task from a project |

User Assignments (4 tools)

| Tool | Description | |------|-------------| | list-project-user-assignments | List which users are assigned to a project | | create-user-assignment | Assign a user to a project | | update-user-assignment | Update assignment (PM role, rate, budget) | | delete-user-assignment | Remove a user from a project |

Users (5 tools)

| Tool | Description | |------|-------------| | get-me | Get the authenticated user's profile | | list-users | List all users in the account | | get-user | Get a user's full profile | | create-user | Create a new user | | update-user | Update a user (or archive with isActive: false) | | delete-user | Delete a user (only if no time entries/expenses) |

Clients (4 tools)

| Tool | Description | |------|-------------| | list-clients | List all clients | | get-client | Get a client's details | | create-client | Create a new client | | update-client | Update a client | | delete-client | Delete a client |

Company (1 tool)

| Tool | Description | |------|-------------| | get-company | Get company settings (plan, capacity, format, currency) |

Requirements

• Node.js 18+
• A Harvest account with API access
• A personal access token and your account ID

Installation

npm install -g @mnicole-dev/harvest-mcp-server

Or run directly with npx:

npx @mnicole-dev/harvest-mcp-server

Configuration

Set these environment variables:

export HARVEST_ACCESS_TOKEN=your-token-here
export HARVEST_ACCOUNT_ID=your-account-id

Claude Code

Add to your ~/.claude.json:

{
  "mcpServers": {
    "harvest": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@mnicole-dev/harvest-mcp-server"],
      "env": {
        "HARVEST_ACCESS_TOKEN": "your-token-here",
        "HARVEST_ACCOUNT_ID": "your-account-id"
      }
    }
  }
}

Claude Desktop

Add to your config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "harvest": {
      "command": "npx",
      "args": ["-y", "@mnicole-dev/harvest-mcp-server"],
      "env": {
        "HARVEST_ACCESS_TOKEN": "your-token-here",
        "HARVEST_ACCOUNT_ID": "your-account-id"
      }
    }
  }
}

Cursor / Windsurf / other MCP clients

Use the stdio transport with npx -y @mnicole-dev/harvest-mcp-server as the command and pass both environment variables.

Examples

Log time

> Log 4 hours on project 12345, task 67890 for today with notes "API development"

Calls create-time-entry with:

{
  "projectId": 12345,
  "taskId": 67890,
  "spentDate": "2026-03-17",
  "hours": 4,
  "notes": "API development"
}

Start a timer

> Start a timer for project 12345, task 67890

Calls start-timer — creates a running time entry. Use stop-timer to stop it.

View this week's entries

> Show me all time entries from Monday to Friday this week

Calls list-time-entries with from and to date parameters.

Create a project

> Create a new billable project "Website Redesign" for client 123, billed by tasks, budget 100 hours

Calls create-project with:

{
  "clientId": 123,
  "name": "Website Redesign",
  "isBillable": true,
  "billBy": "Tasks",
  "budgetBy": "project",
  "budget": 100
}

How it works

1. The MCP client sends a tool call to the server via stdio
2. The server authenticates with the Harvest API v2 using your personal access token
3. The request is forwarded to https://api.harvestapp.com/api/v2/
4. The response is formatted as human-readable text and returned

All requests include the required Authorization, Harvest-Account-Id, and User-Agent headers.

Development

git clone https://github.com/mnicole-dev/harvest-mcp-server.git
cd harvest-mcp-server
pnpm install
pnpm dev          # Run with tsx (requires HARVEST_ACCESS_TOKEN + HARVEST_ACCOUNT_ID)
pnpm build        # Build to dist/

License

MIT