harvest

The Harvest MCP Server provides a Bridge between Claude (and other MCP-enabled assistants) and Harvest, exposing common Harvest resources as MCP tools. With this server you can query and manage time entries, projects, clients, users, and tasks through natural language prompts. Typical interactions include listing time entries, starting and stopping timers, retrieving unsubmitted timesheets, and inspecting project or client details. The server uses a FastMCP-based interface, allowing you to add or extend capabilities by introducing new tool functions in the codebase. To enable usage, configure Claude Desktop to point to the Harvest MCP script and restart the client; you’ll then see a Harvest integration icon and accessible commands within your Claude workflow.

Prerequisites:

• Python 3.10 or higher
• Access to the Harvest API (Account ID and API Key)
• Claude Desktop installed (for integration testing)

Install and run the MCP server:

1. Clone or download the Harvest MCP server repository.
2. Set up a Python virtual environment:

python -m venv venv
# On macOS/Linux
source venv/bin/activate
# On Windows
venv\Scripts\activate

3. Install dependencies:

pip install -r requirements.txt

4. Ensure the uv runner is available. The README example uses uv to execute the server script. If you don’t have uv, install it via pip or your preferred method (e.g., pipx):

pip install uv
# or
pipx install uv

5. Prepare configuration for Claude Desktop (see the provided example like in the README) and place harvest-mcp-server.py in the expected directory (as referenced by --directory).
6. Run the server using the MCP command from your environment (the example uses uv run --directory change_directory harvest-mcp-server.py). Ensure your environment variables HARVEST_ACCOUNT_ID and HARVEST_API_KEY are set (either in the shell or via the config file).

Note: If you prefer using a Python-based workflow, you can alternatively adapt the setup to run harvest-mcp-server.py directly with python, provided the script is compatible with your runtime and dependencies.

Tips and common issues:

• Environment variables: Keep HARVEST_ACCOUNT_ID and HARVEST_API_KEY secure. Do not commit them to public repos.
• API permissions: Ensure the API key has permissions for the actions you intend to perform (time entries, projects, clients, users, tasks).
• Claude Desktop path: Make sure the path in your Claude Desktop config.json points to the correct harvest-mcp-server.py location and that the working directory matches the --directory argument.
• Dependencies: If you encounter missing package errors, verify requirements.txt and install any missing Python packages in your virtual environment.
• Rate limits: Harvest APIs may limit requests; design prompts to batch requests when possible.
• Debugging: Check server logs for authentication errors, invalid query parameters, or missing required fields when creating resources.
• Security: Consider using a dedicated Harvest API key with restricted permissions for this integration.
• Extensibility: The server uses FastMCP. To add new capabilities, implement new functions decorated with @mcp.tool() in the server code and expose them through the MCP interface.