Harvest MCP

@rastko-todorovic/harvest-mcp is a Model Context Protocol (MCP) server for Harvest.

It lets an MCP-compatible AI client connect to the Harvest API to verify your account, inspect assignments/projects/tasks, review time entries, and create new time entries.

What It Can Do

This server currently exposes these tools:

• harvest_whoami
• harvest_list_my_project_assignments
• harvest_list_my_projects
• harvest_list_my_clients
• harvest_list_my_tasks
• harvest_get_project_task_options
• harvest_list_my_time_entries
• harvest_list_today_time_entries
• harvest_get_time_entry
• harvest_create_time_entry
• harvest_update_time_entry
• harvest_delete_time_entry
• harvest_stop_time_entry
• harvest_restart_time_entry

Example prompts:

• "Check my Harvest connection."
• "List my Harvest projects."
• "Show my Harvest time entries for this week."
• "Show my time entries for today."
• "Get Harvest time entry 123456."
• "Show the task options for project 123."
• "Log 1.5 hours on 2026-04-15 for project 123 and task 456 with note API work."
• "Update Harvest time entry 123456 and change notes to Pairing session."
• "Stop Harvest time entry 123456."

Requirements

• Node.js 18+
• a Harvest Personal Access Token
• your Harvest Account ID

Environment Variables

The server reads Harvest credentials from environment variables:

HARVEST_ACCESS_TOKEN=your_token_here
HARVEST_ACCOUNT_ID=your_account_id_here
HARVEST_USER_AGENT="harvest-mcp ([email protected])"

Harvest authentication docs:

• https://help.getharvest.com/api-v2/authentication-api/authentication/authentication/

Install

From npm

npx -y @rastko-todorovic/harvest-mcp

Or install globally:

npm install -g @rastko-todorovic/harvest-mcp

From source

git clone [email protected]:rastkotodorovic/harvest-mcp.git
cd harvest-mcp
npm install
npm run build

npm run build compiles the TypeScript source from src/ into dist/.

Connect To Your MCP Client

Configure your MCP client to launch the published package with npx:

{
  "mcpServers": {
    "harvest": {
      "command": "npx",
      "args": [
        "-y",
        "@rastko-todorovic/harvest-mcp"
      ],
      "env": {
        "HARVEST_ACCESS_TOKEN": "your_token_here",
        "HARVEST_ACCOUNT_ID": "your_account_id_here",
        "HARVEST_USER_AGENT": "harvest-mcp ([email protected])"
      }
    }
  }
}

If you are developing locally instead, you can still launch the built server with Node.js:

{
  "mcpServers": {
    "harvest": {
      "command": "node",
      "args": [
        "/absolute/path/to/harvest-mcp/dist/index.js"
      ],
      "env": {
        "HARVEST_ACCESS_TOKEN": "your_token_here",
        "HARVEST_ACCOUNT_ID": "your_account_id_here",
        "HARVEST_USER_AGENT": "harvest-mcp ([email protected])"
      }
    }
  }
}

Replace /absolute/path/to/harvest-mcp/dist/index.js with the real local path on your machine.

Typical Workflow

For normal use:

1. Publish or install the package from npm.
2. Add the MCP config shown above.
3. Restart or reload your MCP client.

The client will start the server process when needed. You do not need to keep it running manually in a separate terminal.

Development

If you are modifying the code, you can run the server directly from TypeScript:

npm run dev

This is only for local development. Regular users typically only need npm run build.

Project Structure

src/
  harvest/      Harvest API config, client, filters, and query helpers
  tools/        MCP tool definitions
  transports/   MCP transport setup
  schemas/      Zod input schemas
  types/        Harvest response types
  utils/        Output formatting helpers
  index.ts      Process entrypoint
  server.ts     MCP server creation and tool registration

Notes

• This project runs locally through an MCP client over stdio.
• It is not a hosted remote service by itself.
• Set credentials in your MCP client config or shell environment before launch.
• Do not commit real Harvest tokens.

License

MIT