harvest-mcp

imageharvest-mcp

Agent Plugin that connects Harvest through:

1. Harvest’s official remote MCP at https://api.harvestapp.com/mcp (streamable-http) — OAuth, 35 tools.
2. This plugin’s harvest-rest stdio server (servers/harvest-rest) — Harvest API v2 invoice update/delete, messages, payments, user billable/cost rates, invoice item categories, read-only estimates, and project assignment hourly rates. One stdio REST entrypoint.

This is community packaging by M2 AV Consulting, LLC. It is not an official Harvest Inc listing.

Install

1. Install this plugin (Marketplace, cursor.directory, or local ~/.cursor/plugins/local/harvest-mcp).

2. Complete Harvest OAuth when the host prompts you for the official remote MCP. Do not paste personal access tokens into chat or into this repo.

3. For harvest-rest (invoices + rates), set these environment variables on the host (inherited by the stdio server). Do not put secrets in mcp.json (that file is public package data):

   • HARVEST_ACCESS_TOKEN — Harvest personal access token or OAuth access token
   • HARVEST_ACCOUNT_ID — numeric Harvest account ID
   • HARVEST_USER_AGENT — optional; defaults to m2avc-harvest-mcp/<semver> (mn@m2avc.com) where <semver> is the root package.json version (integration author contact, not the end-user Harvest email). See API v2 headers.
   • DANGEROUS_SEND — leave unset. Only 1 (plus Mike GO) unlocks emailing, event_type=send, or send_thank_you=true

4. Node.js 22+ (supported LTS) is required to run harvest-rest. Reload / reconnect MCP if tools do not appear.

Manual Cursor mcp.json equivalent (no plugin). Tokens stay in your local host env, not in the file. Launch the tracked dist binary from the workspace root (no build step in this snippet):

{
  "mcpServers": {
    "harvest": {
      "url": "https://api.harvestapp.com/mcp"
    },
    "harvest-rest": {
      "command": "node",
      "args": ["${workspaceFolder}/servers/harvest-rest/dist/index.js"]
    }
  }
}

Plugin mcp.json uses Agent Plugins schema (streamable-http + stdio).

Domain shapes (for agents)

• TimeEntry = { id, project, task, hours, notes, spent_date, is_running }
• Project = { id, name, client, code, is_active, billing }
• Client = { id, name, is_active }
• Task = { id, name, billable_by_default }
• Expense = { id, project, category, spent_date, total_cost, notes }
• Invoice = { id, client, state, line_items, amounts }
• InvoiceMessage = { id, event_type, recipients, subject, body }
• InvoicePayment = { id, amount, paid_at, paid_date, notes }
• BillableRate = { id, amount, start_date, end_date }
• UserAssignment (harvest-rest PATCH / API v2): { id, project, user, use_default_rates, hourly_rate }
• Official MCP list_project_assignments uses { uses_default_rate, billable_rate } — same meaning, different field names. Do not send the official shape on update_project_user_assignment.

Official MCP creates drafts. Sending, closing, reopening, updating, deleting, and recording payments are on harvest-rest. Never claim an invoice was sent unless create_invoice_message succeeded.

Skills

Official remote MCP tools (35)

Account: get_account_settings, submit_feedback

Timers/time: start_timer, stop_timer, get_running_timer, log_time, list_time_entries, update_time_entry, delete_time_entry, get_time_report

Projects/clients/tasks: list_clients, create_client, update_client, list_projects, create_project, update_project, get_project_budget, list_tasks, create_task, update_task, add_task_to_project, remove_task_from_project

Team: list_users, list_project_assignments, assign_user_to_project, unassign_user_from_project

Expenses: list_expense_categories, list_expenses, get_expense, create_expense, update_expense

Invoices: list_invoices, get_invoice, create_invoice, create_invoice_from_tracked_time

harvest-rest tools (API v2)

Official assign_user_to_project accepts only project_id + user_id. Set rates with update_project_user_assignment (use_default_rates / uses_default_rate + hourly_rate).

See skills/use-harvest-mcp/SKILL.md and servers/harvest-rest/COS-RUNBOOK.md.

What this is / isn’t

Auth

• Official remote MCP: OAuth through the MCP host (preferred day-to-day; least privilege is whatever Harvest ID grants that user/app).
• harvest-rest: PAT or OAuth access token via host env only (HARVEST_ACCESS_TOKEN + HARVEST_ACCOUNT_ID + User-Agent). Prefer a PAT limited to the account you intend to use. Never commit tokens or Account IDs. Never log them.
• Mike human GO is required before Marketplace publish or a public version tag. See servers/harvest-rest/COS-RUNBOOK.md and .github/PULL_REQUEST_TEMPLATE.md.

Harvest API v2 headers and rate limits

Rules from Overview and Authentication:

Endpoint coverage vs official MCP: docs/API_V2_GAP_MATRIX.md.

Extending the REST server

Further official-MCP gaps should be added to servers/harvest-rest/ — one stdio entrypoint — not a second server package.

Author

M2 AV Consulting, LLC — support@m2avc.com

License

MIT. Harvest is a trademark of its owner. This community packaging is unaffiliated with Harvest / Forecast.