Harvest MCP Tool

Connect your Harvest time tracking account to AI assistants like Claude Desktop. Once set up, you can ask Claude things like:

• "What did I log time on this week?"
• "Create a 2-hour time entry for the Acme project today."
• "Show me all my active projects."
• "Stop my running timer."

No coding required to use it — just follow the steps below.

---

What Is This?

This is an MCP server (Model Context Protocol server). Think of it as a small background program that acts as a bridge between Claude Desktop and your Harvest account. Claude talks to this bridge, the bridge talks to Harvest, and the results come back to you in plain English.

---

What You'll Need

Before you start, make sure you have these three things:

Requirement	What It Is	How to Get It
Docker Desktop	The engine that runs this tool safely on your computer	Download here — it's free
Claude Desktop	The AI app you'll chat with	Download here — it's free
Harvest API Credentials	A secret key that lets this tool access your Harvest account	Follow Step 1 below

---

Installation Guide (Step by Step)

Step 1 — Get Your Harvest API Credentials

You need two pieces of information from Harvest: an Account ID and a Personal Access Token.

1. Go to https://id.getharvest.com/developers and log in with your Harvest account.
2. Click "Create New Personal Access Token".
3. Give it a name (anything works, e.g. Claude Integration).
4. Click "Create Personal Access Token".
5. Copy and save:
   • Your Account ID (shown at the top of the page)
   • Your Token (shown after creation — copy it now, it won't be shown again)

Keep these safe. Anyone with these values can access your Harvest account. Never share them publicly.

---

Step 2 — Install Docker Desktop

1. Visit https://www.docker.com/products/docker-desktop/
2. Click "Download Docker Desktop" for your operating system (Mac or Windows).
3. Open the downloaded file and follow the installation prompts.
4. Once installed, open Docker Desktop and wait for it to fully start (you'll see a green icon in your menu bar or system tray).

Docker Desktop needs to be running whenever you use this tool with Claude.

---

Step 3 — Install Claude Desktop

1. Visit https://claude.ai/download
2. Download and install Claude Desktop for your operating system.
3. Open Claude Desktop and sign in (or create a free account).

---

Step 4 — Configure Claude Desktop to Use This Tool

This is the key step. You'll edit a configuration file that tells Claude Desktop about the Harvest tool.

On Mac:

1. Open Finder.
2. In the menu bar, click Go → Go to Folder... (or press Cmd + Shift + G).
3. Type this path and press Enter:

   ~/Library/Application Support/Claude
   

4. Look for a file called claude_desktop_config.json. If it doesn't exist, create a new text file with that exact name.
5. Open the file with a text editor (TextEdit works — if using TextEdit, go to Format → Make Plain Text first).

On Windows:

1. Press Windows + R, type %APPDATA%\Claude and press Enter.
2. Look for claude_desktop_config.json. Create it if it doesn't exist.
3. Open it with Notepad.

Add the Configuration:

Paste the following into the file. Replace YOUR_ACCOUNT_ID and YOUR_API_TOKEN with the values you copied in Step 1:

{
  "mcpServers": {
    "harvest": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "HARVEST_ACCOUNT_ID",
        "-e",
        "HARVEST_TOKEN",
        "harvest-mcp-tool"
      ],
      "env": {
        "HARVEST_ACCOUNT_ID": "YOUR_ACCOUNT_ID",
        "HARVEST_TOKEN": "YOUR_API_TOKEN"
      }
    }
  }
}

If the file already has content (starts with {), don't replace everything — just add the "harvest": { ... } block inside the existing "mcpServers": { } section.

Save the file.

---

Step 5 — Restart Claude Desktop

1. Fully quit Claude Desktop (don't just close the window).
   • Mac: Right-click the Claude icon in the Dock → Quit
   • Windows: Right-click the Claude icon in the system tray → Exit
2. Reopen Claude Desktop.

You should now see a small hammer icon (🔨) or tools indicator in the chat interface, showing that MCP tools are connected.

---

Step 6 — Test It!

Type a message to Claude like:

"Use Harvest to show me my recent time entries."

Claude will use this tool to fetch your data and reply with the results.

---

Available Commands

Once connected, you can ask Claude to do any of the following:

Time Entries

What You Can Ask	What It Does
"Show my time entries this week"	Lists time entries, optionally filtered by date
"Get time entry 12345"	Retrieves a specific entry by ID
"Log 2 hours on project X, task Y for today"	Creates a new time entry
"Start a timer for project X"	Creates a running time entry
"Stop my running timer"	Stops an active timer
"Restart timer for entry 12345"	Restarts a stopped entry
"Update entry 12345 to 3 hours"	Updates an existing entry
"Delete time entry 12345"	Deletes an entry

Projects & Tasks

What You Can Ask	What It Does
"List my active projects"	Shows all active projects
"Show all tasks"	Lists all available tasks

Account

What You Can Ask	What It Does
"Who am I in Harvest?"	Returns your Harvest user profile

---

Troubleshooting

Claude doesn't show any Harvest tools:

• Make sure Docker Desktop is open and running (green icon in menu/tray).
• Double-check that you fully quit and restarted Claude Desktop after editing the config file.
• Verify the JSON in claude_desktop_config.json is valid — commas and brackets must be correct. Use jsonlint.com to check.

"HARVEST_ACCOUNT_ID and HARVEST_TOKEN must be set" error:

• Make sure you replaced YOUR_ACCOUNT_ID and YOUR_API_TOKEN with your actual values in the config file.

Docker command not found:

• Docker Desktop isn't installed or isn't running. Go back to Step 2.

401 Unauthorized from Harvest:

• Your token may have expired or been entered incorrectly. Go back to Step 1 and generate a new token.

---

For Developers

If you want to build or modify this tool locally:

# Clone the repo
git clone https://github.com/harvest-mcp-tool/harvest-mcp-tool.git
cd harvest-mcp-tool

# Build the Docker image locally
docker build -t harvest-mcp-tool .

# Then use "harvest-mcp-tool" in your config

Tech stack:

• Python 3.13
• FastMCP for the MCP server framework
• httpx for HTTP requests
• uv for dependency management
• Docker for packaging and distribution

Environment variables:

Variable	Description
HARVEST_ACCOUNT_ID	Your Harvest Account ID
HARVEST_TOKEN	Your Harvest Personal Access Token
MCP_PORT	Port to run on (default: 8080)

Copy .env.example to .env and fill in your credentials for local development.

---

License

MIT