npm package: @mnicole-dev/harvest-mcp-server
Description: MCP server for the Harvest time tracking API (v2)
Latest version: 1.0.0

# @mnicole-dev/harvest-mcp-server

A [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server for the [Harvest](https://www.getharvest.com) 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](https://id.getharvest.com/developers) and your account ID

## Installation

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

Or run directly with `npx`:

```bash
npx @mnicole-dev/harvest-mcp-server
```

## Configuration

Set these environment variables:

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

### Claude Code

Add to your `~/.claude.json`:

```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):

```json
{
  "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:
```json
{
  "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:
```json
{
  "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

```bash
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