valtirallc/harvest-mcp-server

Harvest MCP Server

A complete Model Context Protocol (MCP) server for the Harvest API v2, written in Go. Exposes all 64 Harvest API endpoints as MCP tools for use with Claude and other MCP clients.

Quick Start

1. Get Credentials

Access Token:

• Visit https://id.getharvest.com/developers
• Create a Personal Access Token
• Copy the token

Account ID:

• Log in to Harvest → Account Settings
• Find your Account ID

2. Build

cd harvest-mcp-server
go build -o harvest-mcp ./cmd/harvest-mcp

3. Configure

export HARVEST_ACCESS_TOKEN="YOUR_TOKEN"
export HARVEST_ACCOUNT_ID="YOUR_ID"

4. Run

./harvest-mcp

5. Use with Claude Desktop

Edit ~/.config/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "harvest": {
      "command": "/path/to/harvest-mcp",
      "env": {
        "HARVEST_ACCESS_TOKEN": "YOUR_TOKEN",
        "HARVEST_ACCOUNT_ID": "YOUR_ID"
      }
    }
  }
}

Restart Claude Desktop. The Harvest tools are now available!

Features

✅ 64 MCP Tools - Complete Harvest API v2 coverage (100%) ✅ Production Ready - Rate limiting, caching, error handling ✅ Zero Config - Environment variables only ✅ Fast - Smart caching reduces API calls ✅ Reliable - Automatic rate limiting (100/15 sec) ✅ Type Safe - Full Go type safety

Available Tools

Configuration

Environment Variables

# Required
HARVEST_ACCESS_TOKEN=YOUR_TOKEN        # From https://id.getharvest.com/developers
HARVEST_ACCOUNT_ID=YOUR_ID             # From Harvest account settings

# Optional
LOG_LEVEL=info                          # debug|info|warn|error (default: info)
CACHE_MAX_SIZE=1048576                  # Max cache size in bytes (default: 1MB)
CACHE_TTL=300                           # Cache time-to-live in seconds (default: 5min)
CACHE_MAX_ITEMS=1000                    # Max items in cache (default: 1000)
REQUEST_TIMEOUT=30                      # Request timeout in seconds (default: 30)
MAX_RETRIES=3                           # Max retry attempts (default: 3)
DEBUG_LOG_REQUESTS=false                # Verbose logging (default: false)

Using .env File

Create .env in project root:

HARVEST_ACCESS_TOKEN=YOUR_TOKEN
HARVEST_ACCOUNT_ID=YOUR_ID
LOG_LEVEL=info

The application loads it automatically.

Testing & Debugging

Start with Debug Logging

LOG_LEVEL=debug ./harvest-mcp 2>&1 | tee server.log

Test with Python Script

import subprocess
import json

def test():
    process = subprocess.Popen(
        ['./harvest-mcp'],
        stdin=subprocess.PIPE,
        stdout=subprocess.PIPE,
        text=True,
        env={'HARVEST_ACCESS_TOKEN': 'YOUR_TOKEN', 'HARVEST_ACCOUNT_ID': 'YOUR_ID'}
    )
    
    request = '{"jsonrpc":"2.0","method":"tools/list","id":1}'
    process.stdin.write(request + '\n')
    process.stdin.flush()
    
    response = process.stdout.readline()
    result = json.loads(response)
    print(f"Tools: {len(result['result']['tools'])}")
    
    process.terminate()

test()

View Logs

# Live logs
tail -f server.log

# Search for errors
grep -i error server.log

# Count errors
grep -ic error server.log

Production Setup

Performance Tuning

For high-traffic scenarios:

export CACHE_MAX_SIZE=5242880          # 5MB
export CACHE_TTL=600                   # 10 minutes
export CACHE_MAX_ITEMS=5000
export MAX_RETRIES=5

Logging

Production recommended:

export LOG_LEVEL=warn                  # Only warnings/errors
export DEBUG_LOG_REQUESTS=false        # No verbose logging

Architecture

Structure

harvest-mcp-server/
├── cmd/harvest-mcp/          # Entry point
├── internal/
│   ├── config/               # Configuration
│   ├── harvest/              # Harvest API client
│   └── server/               # MCP server + tools
│       ├── middleware.go      # Rate limiting, caching
│       ├── company.go         # Company tool
│       ├── clients.go         # Client tools
│       ├── contacts.go        # Contact tools
│       ├── projects.go        # Project tools
│       ├── tasks.go           # Task tools
│       ├── users.go           # User tools
│       ├── time_entries.go    # Time entry tools
│       ├── assignments.go     # Assignment tools
│       ├── invoices.go        # Invoice tools
│       ├── estimates.go       # Estimate tools
│       ├── expenses.go        # Expense tools
│       └── reports.go         # Report tools
├── pkg/mcp/                  # MCP protocol types
└── go.mod/go.sum            # Dependencies

Key Features

Rate Limiting:

• Token bucket algorithm
• 100 requests per 15 seconds (Harvest limit)
• Automatic rate limiting - transparent to caller
• Less than 1ms overhead

Caching:

• TTL-based in-memory cache
• Configurable size and TTL
• Automatic background cleanup
• Smart cache invalidation

Error Handling:

• Structured logging with context
• Comprehensive input validation
• Clear error messages
• Automatic retries with backoff

Troubleshooting

"API error (status 401)"

Token invalid or expired:

• Generate new token: https://id.getharvest.com/developers
• Verify token is set: echo $HARVEST_ACCESS_TOKEN
• Check it has no typos

"API error (status 403)"

Account ID incorrect:

• Verify Account ID in Harvest settings
• Check token has proper permissions
• Verify both token and ID are correct

"HARVEST_ACCESS_TOKEN environment variable is required"

Set credentials before running:

export HARVEST_ACCESS_TOKEN="YOUR_TOKEN"
export HARVEST_ACCOUNT_ID="YOUR_ID"
./harvest-mcp

Or use .env file in project root.

Server is Slow

Enable caching:

export CACHE_TTL=600                # 10 minutes
export CACHE_MAX_SIZE=5242880       # 5MB

Or check logs:

LOG_LEVEL=debug ./harvest-mcp 2>&1 | tee server.log

Development

Building

go build -o harvest-mcp ./cmd/harvest-mcp

Testing

go test ./...

Code Organization

Each resource type has its own file in internal/server/:

• One file per resource (e.g., clients.go, projects.go)
• Tool definitions and handlers together
• Consistent error handling
• Clean separation of concerns

What's Included

✅ All 64 MCP tools fully implemented ✅ 100% Harvest API v2 coverage ✅ Rate limiting (100/15 sec) ✅ Response caching (TTL-based) ✅ Error handling & validation ✅ Structured logging ✅ Production ready ✅ Fully documented

Requirements

• Go 1.21+
• Harvest account with API access
• Personal access token
• Internet connection

Project Status

Status: ✅ Production Ready
Tools: 64/64 implemented
Coverage: 100% Harvest API v2
Quality: Enterprise-grade
Binary Size: 8.6 MB
Build Time: ~5-10 seconds

Support & Docs

• Quick setup issues? → Check "Quick Start" section above
• Configuration help? → See "Configuration" section
• Testing? → See "Testing & Debugging" section
• Production? → See "Production Setup" section
• Harvest API questions? → https://help.getharvest.com/api-v2/

License

See LICENSE file.

Acknowledgments

• Built with Model Context Protocol
• Powered by Harvest API v2