Harvest MCP Server

Time tracking using Claude.

The most complete Harvest integration for Claude. 54 tools covering all important endpoints of the Harvest API v2 — time entries, projects, tasks, clients, expenses, team assignments, and reports.

Built in TypeScript (not Python like most MCP servers for Harvest time tracking), bundled into a single file — no runtime dependencies to install.

Works with Claude Desktop Extension (one-click install, no config files), Claude Cowork Plugin (skills + slash commands), and Claude Code.

For Users

Quick Install (Claude Desktop Extension) — recommended

1. Get your Harvest credentials — go to id.getharvest.com/developers, click "Create New Personal Access Token", and note your Access Token and Account ID
2. Download harvest-mcp.mcpb from the latest release
3. Double-click the .mcpb file (or drag it into Claude Desktop settings)
4. Enter your credentials when prompted — they're stored securely in your OS keychain

That's it. No terminal, no JSON files, no build steps. The extension installs the MCP server locally and handles everything — much simpler than servers that require manually editing JSON config files.

This is all you need to get started. The Cowork plugin below is optional but recommended.

Install (Claude Cowork Plugin) — optional

1. Get your Harvest credentials (same as above)
2. Download harvest-plugin.zip from the latest release
3. In Claude Desktop, switch to the Cowork tab
4. Click Customize in the left sidebar
5. Click Browse plugins, then upload the harvest-plugin.zip file
6. Enter your credentials when prompted

The plugin adds slash commands (/log-time, /timer, /weekly-report, /catchup, /unsubmitted) and skills for time management, project analysis, and context-aware Harvest conventions.

What You Can Do

Track Time — create, update, and delete time entries. Start and stop timers. Log hours manually or with start/end times.

Manage Projects — create projects, assign users, set budgets, configure billing. Full CRUD on projects, tasks, and clients.

Track Expenses — log expenses by category, manage expense categories with unit-based pricing (e.g. mileage).

Get Reports — time reports by client/project/task/team, expense reports, project budget reports, uninvoiced amounts.

Team Management — assign users to projects, manage roles and rates, view project assignments.

All 54 Tools

| Area | Tools | |------|-------| | Time Entries | list_time_entries get_time_entry create_time_entry update_time_entry delete_time_entry restart_timer stop_timer | | Projects | list_projects get_project create_project update_project delete_project list_project_task_assignments | | Tasks | list_tasks get_task create_task update_task delete_task | | Clients | list_clients get_client create_client update_client delete_client | | Users | get_me get_user list_users list_my_project_assignments list_user_project_assignments | | Expenses | list_expenses get_expense create_expense update_expense delete_expense | | Expense Categories | list_expense_categories get_expense_category create_expense_category update_expense_category delete_expense_category | | Project User Assignments | list_all_user_assignments list_project_user_assignments get_project_user_assignment create_project_user_assignment update_project_user_assignment delete_project_user_assignment | | Time Reports | time_report_by_clients time_report_by_projects time_report_by_tasks time_report_by_team | | Expense Reports | expense_report_by_clients expense_report_by_projects expense_report_by_categories expense_report_by_team | | Other Reports | project_budget_report uninvoiced_report |

Guided Prompts

| Prompt | What it does | |--------|-------------| | log-time | Walks you through picking a project, task, hours, and notes | | weekly-summary | Summarizes the week's entries by project/client with gap detection | | timer | Quick start/stop/status for running timers |

Getting Your Harvest API Credentials

1. Go to id.getharvest.com/developers
2. Sign in with your Harvest account
3. Click "Create New Personal Access Token"
4. Give it a name (e.g. "Claude")
5. Copy the Token and note your Account ID (shown on the same page)

For Developers

Prerequisites

• Node.js 18+
• pnpm

Setup

git clone https://github.com/mikkokam/harvest-cowork-mcp.git
cd harvest-cowork-mcp
pnpm install

Build

pnpm build                    # Compile TypeScript + bundle with esbuild
pnpm validate                 # Validate the .mcpb manifest
pnpm pack:mcpb                # Build + package as .mcpb extension

Run Locally (for development)

export HARVEST_ACCESS_TOKEN="your-token"
export HARVEST_ACCOUNT_ID="your-account-id"
node packages/mcp-server/dist/index.mjs

Or add to Claude Desktop / Claude Code config manually:

{
  "mcpServers": {
    "harvest": {
      "command": "node",
      "args": ["/absolute/path/to/harvest-cowork-mcp/packages/mcp-server/dist/index.mjs"],
      "env": {
        "HARVEST_ACCESS_TOKEN": "your-token",
        "HARVEST_ACCOUNT_ID": "your-account-id"
      }
    }
  }
}

Project Structure

harvest-cowork-mcp/
├── packages/
│   ├── mcp-server/
│   │   ├── src/
│   │   │   ├── index.ts              # Server entry point
│   │   │   ├── harvest-client.ts     # Harvest API v2 HTTP client
│   │   │   ├── types.ts              # TypeScript types for all API entities
│   │   │   ├── tools/
│   │   │   │   ├── time-entries.ts    # 7 tools
│   │   │   │   ├── projects.ts       # 6 tools
│   │   │   │   ├── tasks.ts          # 5 tools
│   │   │   │   ├── clients.ts        # 5 tools
│   │   │   │   ├── users.ts          # 5 tools
│   │   │   │   ├── expenses.ts       # 5 tools
│   │   │   │   ├── expense-categories.ts  # 5 tools
│   │   │   │   ├── project-user-assignments.ts  # 6 tools
│   │   │   │   └── reports.ts        # 10 tools
│   │   │   └── prompts/
│   │   │       ├── log-time.ts
│   │   │       ├── weekly-summary.ts
│   │   │       └── timer.ts
│   │   ├── manifest.json             # .mcpb extension manifest
│   │   ├── package.json
│   │   └── tsconfig.json
│   └── plugin/                       # Claude Cowork plugin (skills + commands)
├── package.json                      # Workspace root
├── pnpm-workspace.yaml
└── .gitignore

Adding New Endpoints

The pattern is consistent across all tools:

1. Add types in types.ts (entity interface, create/update params, list params)
2. Add client methods in harvest-client.ts
3. Create tool file in tools/ with registerXTools() function
4. Register in index.ts
5. Update manifest in manifest.json (tool name + description)
6. Build with pnpm build

Tech Stack

• MCP TypeScript SDK ^1.27
• Zod for tool input schema validation
• esbuild for single-file bundling
• @anthropic-ai/mcpb for Desktop Extension packaging
• STDIO transport — runs as a subprocess of Claude

Harvest API Reference

Built on Harvest API v2. Covers:

• Time Entries
• Projects + Task Assignments + User Assignments
• Tasks
• Clients
• Users + Project Assignments
• Expenses + Categories
• Time Reports + Expense Reports + Project Budget + Uninvoiced

How This Was Built

This entire MCP server — 54 tools, types, client, manifest, packaging — was built in a single session using Claude Cowork with the Claude Code VS Code Extension. Claude read the Harvest API docs, wrote all the code, validated the manifest, built the .mcpb, and pushed to GitHub. No config files were edited by hand.

License

MIT