Harvest MCP Server

Connect your AI assistant to Harvest time tracking. Query time entries, analyze profitability, track utilization, and manage your Harvest data through natural language.

Live Server: https://harvest-mcp.southleft.com

Quick Start

Claude Desktop (Recommended)

1. Open Claude Desktop → Settings → Connectors
2. Click Add Connector
3. Enter: https://harvest-mcp.southleft.com/mcp
4. Click Connect

On first use, you'll receive an OAuth link to connect your Harvest account.

Claude Code CLI

claude mcp add --transport http harvest https://harvest-mcp.southleft.com/mcp

Manual Configuration

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "harvest": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://harvest-mcp.southleft.com/mcp"]
    }
  }
}

Example Prompts

Time Tracking

"What did I work on today?"

"Show me all my time entries from last week"

"How many hours did I log on the Acme project this month?"

"Start a timer for the Design task on Project X"

"Stop my running timer"

Team & Client Analysis

"Who on my team logged the most hours last month?"

"Show me all time entries for client Acme Corp"

"Get the contact information for everyone at Initech"

"What projects is Sarah working on?"

"List all active clients"

Profitability & Utilization

"What's our profitability on the Acme project this quarter?"

"Compare profitability across all clients for 2024"

"What's our team utilization rate this month?"

"Show me billable vs non-billable breakdown by team member"

"Which projects are most profitable?"

Budget Performance

"Which employees went over their project budgets this quarter?"

"Show me top performers who came in under budget"

"Who are the repeat offenders going over budget on multiple projects?"

"Compare budget variance by team member for 2024"

Invoicing & Expenses

"Show me all unpaid invoices"

"What invoices are open for Acme Corp?"

"List all expenses for the Johnson project"

"What's been billed vs unbilled this quarter?"

Aggregation & Reporting

"Sum up hours by project for November"

"Break down time by client and user for Q4"

"Weekly hours summary for December"

"Show me time trends by month for 2024"

Available Tools (21)

Time Tracking

Company & Team

Clients & Contacts

Projects & Tasks

Invoicing & Expenses

Analytics & Compute

Utilities

Self-Hosting

Cloudflare Workers (Recommended)

1. Clone and install

   git clone https://github.com/southleft/harvest-mcp.git
   cd harvest-mcp
   npm install
   

2. Create Harvest OAuth App

   • Go to Harvest Developers
   • Create a new OAuth2 application
   • Set redirect URI to https://your-worker.workers.dev/callback
   • Note your Client ID and Client Secret

3. Configure Cloudflare

   # Update wrangler.toml with your account_id
   
   # Create KV namespaces
   npx wrangler kv:namespace create SESSIONS
   npx wrangler kv:namespace create RATES_CONFIG
   
   # Update wrangler.toml with the namespace IDs
   
   # Set secrets
   echo "YOUR_CLIENT_ID" | npx wrangler secret put HARVEST_CLIENT_ID
   echo "YOUR_CLIENT_SECRET" | npx wrangler secret put HARVEST_CLIENT_SECRET
   echo "YOUR_SESSION_SECRET" | npx wrangler secret put SESSION_SECRET
   

4. Deploy

   npm run deploy
   

Node.js Server

cp .env.example .env
# Edit .env with your Harvest credentials

npm run dev      # Development
npm run build && npm start  # Production

Environment Variables

Architecture

┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│  Claude/MCP     │────▶│  Cloudflare      │────▶│  Harvest        │
│  Client         │◀────│  Workers         │◀────│  API            │
└─────────────────┘     └──────────────────┘     └─────────────────┘
                               │
                               ▼
                        ┌──────────────────┐
                        │  Cloudflare KV   │
                        │  (Sessions)      │
                        └──────────────────┘

Stack:

• Hono - Web framework
• MCP SDK - Model Context Protocol
• Cloudflare KV - Session storage
• Harvest API v2 - Time tracking API

API Endpoints

Development

npm install           # Install dependencies
npm run dev:workers   # Run locally with wrangler
npm test              # Run tests
npm run lint          # Lint code
npm run format        # Format code

Project Structure

src/
├── workers/          # Cloudflare Workers entry point
│   ├── index.ts      # Hono app with MCP endpoint
│   ├── config.ts     # Workers config loader
│   └── kv-session-store.ts
├── tools/            # MCP tool implementations
│   └── index.ts      # All tool registrations
├── harvest/          # Harvest API client
│   ├── client.ts     # API client with caching
│   ├── types.ts      # TypeScript types
│   ├── cache.ts      # LRU cache
│   └── rate-limiter.ts
├── compute/          # Analytics engines
│   ├── profitability.ts
│   ├── utilization.ts
│   └── aggregation.ts
├── auth/             # OAuth implementation
├── session/          # Session management
├── rates/            # Rate resolution service
├── entities/         # Entity resolution (fuzzy search)
└── schema/           # Schema documentation

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License - see LICENSE for details.

Built by Southleft