harvest

The Harvest MCP server connects Claude-powered assistants to Harvest time tracking data through the MCP protocol. It exposes a structured suite of tools that let you list, query, and manipulate Harvest resources such as time entries, clients, projects, invoices, and more, enabling natural-language prompts to drive your Harvest workflow. Once connected, Claude can perform tasks like retrieving time entries for a user, starting or stopping timers, analyzing profitability and utilization, and generating aggregates across clients, projects, and team members. The available tools cover time tracking, company and team data, clients and contacts, projects and tasks, invoicing and expenses, analytics, and utilities that help resolve entities and fetch schema definitions. You can use these capabilities via the MCP endpoint at /mcp and interact with Harvest through natural-language commands or structured tool invocations.

Prerequisites:

• Node.js and npm installed on your machine or server.
• Access to the internet to fetch the mcp-remote package via npx.
• If self-hosting, familiarity with Cloudflare Workers (optional, per deployment method).

Installation steps (Node.js / CLI-driven via npx):

1. Ensure you have Node.js and npm installed. Verify with: node -v npm -v

2. Install or run the MCP server endpoint directly using NPX (no local installation required): npx -y mcp-remote https://harvest-mcp.southleft.com/mcp

3. If you prefer to host locally, clone the repository (or use the provided installer in the project): git clone https://github.com/southleft/harvest-mcp.git cd harvest-mcp npm install npm run dev # Development server (or the appropriate production command as documented)

4. For self-hosted Cloudflare Workers deployment (Cloudflare recommended):

   • Clone and install dependencies: git clone https://github.com/southleft/harvest-mcp.git cd harvest-mcp npm install
   • Configure OAuth and secrets as described in the README (HARVEST_CLIENT_ID, HARVEST_CLIENT_SECRET, SESSION_SECRET).
   • Deploy using the provided commands (e.g., npm run deploy) as per the project’s self-hosting instructions.

5. Configure a client to connect via MCP:

   • In Claude, add an MCP endpoint pointing to the server URL /mcp (e.g., https://harvest-mcp.southleft.com/mcp).
   • Authenticate when prompted to authorize Harvest access for the assistant.

Prerequisites may vary slightly depending on your hosting method (Node.js local server vs. Cloudflare Workers). Always refer to the latest project documentation for environment-specific steps.

Notes and tips:

• The MCP server relies on Harvest OAuth credentials (HARVEST_CLIENT_ID and HARVEST_CLIENT_SECRET) and a session secret for secure operation. Ensure these are configured in your environment when self-hosting.
• If you deploy via Cloudflare Workers, you’ll need to set up KV namespaces (SESSIONS, RATES_CONFIG) and supply Secrets for HARVEST_CLIENT_ID, HARVEST_CLIENT_SECRET, and SESSION_SECRET.
• The recommended quick-start uses npx to avoid local installation, but for production you may prefer a persistent local or cloud deployment (Node.js server or Cloudflare Workers).
• The available tools cover a broad range of Harvest capabilities. Use descriptive natural language prompts to leverage search and filtering capabilities (e.g., list time entries for a date range, compute profitability by project, or aggregate time by client). If a prompt cannot be resolved directly, the MCP layer will guide you to the appropriate tool with parameters.
• Ensure the OAuth redirect URL is whitelisted in your Harvest application settings when configuring OAuth in the Harvest Developer console.
• If you encounter CORS or domain origin issues in Claude, consider adjusting ALLOWED_ORIGINS or hosting the MCP server under a domain that matches your Claude deployment origin.