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
- Open Claude Desktop → Settings → Connectors
- Click Add Connector
- Enter:
https://harvest-mcp.southleft.com/mcp - Click Connect
On first use, you'll receive an OAuth link to connect your Harvest account.
claude mcp add --transport http harvest https://harvest-mcp.southleft.com/mcpAdd to ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"harvest": {
"command": "npx",
"args": ["-y", "mcp-remote", "https://harvest-mcp.southleft.com/mcp"]
}
}
}"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"
"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"
"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?"
"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"
"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?"
"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"
| Tool | Description |
|---|---|
harvest_list_time_entries |
List and filter time entries by user, client, project, date range |
harvest_get_time_entry |
Get a specific time entry by ID |
harvest_create_time_entry |
Create new time entries with optional timer |
harvest_stop_timer |
Stop a running timer |
harvest_delete_time_entry |
Delete a time entry |
| Tool | Description |
|---|---|
harvest_get_company |
Get company/account information |
harvest_get_current_user |
Get current user info |
harvest_list_users |
List all users with filters |
| Tool | Description |
|---|---|
harvest_list_clients |
List all clients |
harvest_list_contacts |
List client contacts (people associated with clients) |
| Tool | Description |
|---|---|
harvest_list_projects |
List all projects with filters |
harvest_list_tasks |
List all tasks |
| Tool | Description |
|---|---|
harvest_list_invoices |
List invoices with state/date filters |
harvest_list_expenses |
List expenses with filters |
| Tool | Description |
|---|---|
harvest_compute_profitability |
Calculate profitability (time-based, invoice-based, or hybrid) |
harvest_compute_utilization |
Calculate utilization with capacity tracking |
harvest_aggregate_time |
Aggregate time by client, project, user, date, week, or month |
harvest_compute_budget_performance |
Analyze employee performance based on budget adherence per project |
| Tool | Description |
|---|---|
harvest_get_rates |
Get cost and billable rates with fallback support |
harvest_resolve_entities |
Fuzzy search for entities by name |
harvest_get_schema |
Get schema definitions and enum values (no auth required) |
-
Clone and install
git clone https://github.com/southleft/harvest-mcp.git cd harvest-mcp npm install -
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
-
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
-
Deploy
npm run deploy
cp .env.example .env
# Edit .env with your Harvest credentials
npm run dev # Development
npm run build && npm start # Production| Variable | Description | Required |
|---|---|---|
HARVEST_CLIENT_ID |
Harvest OAuth Client ID | Yes |
HARVEST_CLIENT_SECRET |
Harvest OAuth Client Secret | Yes |
SESSION_SECRET |
Secret for session encryption | Yes |
SESSION_TTL_HOURS |
Session lifetime (default: 24) | No |
ALLOWED_ORIGINS |
CORS allowed origins | No |
DEFAULT_COST_RATE |
Fallback cost rate | No |
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
│ 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
| Endpoint | Method | Description |
|---|---|---|
/ |
GET | Landing page |
/health |
GET | Health check |
/mcp |
POST | MCP protocol endpoint |
/callback |
GET | OAuth callback |
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 codesrc/
├── 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
Contributions are welcome! Please feel free to submit a Pull Request.
MIT License - see LICENSE for details.
Built by Southleft