harvest

Harvest MCP Server provides a Bridge between an MCP client (like Claude Desktop) and the Harvest time tracking API. It exposes a set of MCP-compatible tools that map to Harvest resources such as time entries, projects, tasks, clients, users, expenses, invoices, estimates, and reports. Once configured, you can prompt your MCP client to perform actions like listing time entries, creating time entries, starting and stopping timers, and generating reports, all through the unified MCP interface. The server authenticates with Harvest using a personal access token you supply in the environment, and your MCP client communicates with the server using the MCP protocol, enabling automated workflows and conversational prompts to manage your Harvest data.

Prerequisites:

• Node.js 18 or newer installed on your system
• npm (comes with Node.js) or npm/yarn for package installation
• Access to a Harvest account with API access and a generated Personal Access Token

Installation steps:

1. Install the MCP server package globally (optional):

npm install -g @ianaleck/harvest-mcp-server

2. Or install locally in your project:

npm install @ianaleck/harvest-mcp-server

3. Prepare environment variables (see .env.example in the repository):

cp .env.example .env

4. Add your Harvest credentials to the environment file or your process environment:

HARVEST_ACCESS_TOKEN=your_harvest_personal_access_token
HARVEST_ACCOUNT_ID=your_harvest_account_id

5. Start the server using the recommended MCP configuration (example given in the mcp_config):

# If installed globally via npx as shown in the example
# or run your own node script to boot the MCP server according to the package docs

6. Verify the server is running and the MCP client can connect, then configure your MCP client with the server name you chose (e.g., harvest) and the provided command/args.

Optional: Run tests and build locally if you are developing this server:

npm test
npm run build

Environment variables are required for Harvest authentication. If using a CI/CD environment, ensure HARVEST_ACCESS_TOKEN and HARVEST_ACCOUNT_ID are securely provided. The MCP server mirrors Harvest API capabilities; when using features like time entries, projects, or reports, ensure the access token has permission to those endpoints. If you encounter rate limit issues, consider enabling any built-in retry/backoff strategies described in the project docs and respect Harvest API rate limits (100 requests per 15 seconds). For local development, keep your .env/.env.example in sync with the required variables. If you need to update tokens, regenerate tokens in Harvest and update the env accordingly.