🌾 Harvest MCP Server

Unofficial Model Context Protocol (MCP) server for seamless integration with the Harvest time tracking API

⚠️ Disclaimer: This is an unofficial, third-party integration with the Harvest API. This project is not affiliated with, endorsed by, or sponsored by Harvest or Forecast (the company behind Harvest).

✨ Features

🔗 Complete Harvest API v2 Coverage - 40+ tools covering all major endpoints
🛡️ Type-Safe - Full TypeScript support with Zod validation
⚡ High Performance - Built with async/await and proper rate limiting
🧪 Thoroughly Tested - Comprehensive unit, integration, and contract tests
📊 Rich Logging - Structured logging for debugging and monitoring
🔄 Auto-Retry - Intelligent retry logic with exponential backoff
📖 MCP Compliant - Works with Claude Desktop and other MCP clients

🚀 Quick Start

Prerequisites

Node.js 18+
Harvest account with API access
MCP-compatible client (like Claude Desktop)

Installation

bash

# Install globally
npm install -g @ianaleck/harvest-mcp-server

# Or install locally
npm install @ianaleck/harvest-mcp-server

Configuration

Get your Harvest API credentials:
- Go to Harvest → Settings → Developers → Personal Access Tokens
- Create a new token
- Note your Account ID (visible in URL or settings)
Configure your MCP client (e.g., Claude Desktop):

config.json

{
  "mcpServers": {
    "harvest": {
      "command": "npx",
      "args": ["-y", "@ianaleck/harvest-mcp-server"],
      "env": {
        "HARVEST_ACCESS_TOKEN": "your_harvest_personal_access_token",
        "HARVEST_ACCOUNT_ID": "your_harvest_account_id"
      }
    }
  }
}

Start using with Claude!

🎯 What You Can Do

Once connected, you can ask Claude to help with:

⏱️ Time Tracking

"Show me all my time entries for this week"
"Start a timer for the 'Development' task on the 'Website Project'"
"How many hours did I work on Project X last month?"

📋 Project Management

"List all active projects for client Acme Corp"
"Create a new project called 'Mobile App' for client TechStart"
"Show me project budget vs actual time spent"

👥 Team Management

"Who are all the users in our Harvest account?"
"Show me John's time entries for last week"

💰 Financial Tracking

"Generate an expense report for Q4"
"Show me all unpaid invoices"
"What's our total billable hours this month?"

🛠️ Available Tools

📊 Company & Account (1 tool)

get_company - Get company information and settings

⏰ Time Entries (8 tools)

list_time_entries - List time entries with filtering
get_time_entry - Get specific time entry details
create_time_entry - Create new time entry
update_time_entry - Update existing time entry
delete_time_entry - Delete time entry
start_timer - Start a timer for a task
stop_timer - Stop running timer
restart_timer - Restart a previous time entry

🏗️ Projects (7 tools)

list_projects - List all projects with filtering
get_project - Get specific project details
create_project - Create new project
update_project - Update project details
delete_project - Delete project
list_project_task_assignments - List task assignments for project
create_project_task_assignment - Assign task to project
update_project_task_assignment - Update task assignment
delete_project_task_assignment - Remove task assignment

📝 Tasks (5 tools)

list_tasks - List all tasks
get_task - Get specific task details
create_task - Create new task
update_task - Update task details
delete_task - Delete task

🏢 Clients (5 tools)

list_clients - List all clients
get_client - Get specific client details
create_client - Create new client
update_client - Update client details
delete_client - Delete client

👤 Users (6 tools)

list_users - List all users in account
get_user - Get specific user details
get_current_user - Get current authenticated user
create_user - Create new user
update_user - Update user details
delete_user - Delete user

💸 Expenses (6 tools)

list_expenses - List expenses with filtering
get_expense - Get specific expense details
create_expense - Create new expense
update_expense - Update expense details
delete_expense - Delete expense
list_expense_categories - List all expense categories

🧾 Invoices (5 tools)

list_invoices - List invoices with filtering
get_invoice - Get specific invoice details
create_invoice - Create new invoice
update_invoice - Update invoice details
delete_invoice - Delete invoice

📋 Estimates (5 tools)

list_estimates - List estimates with filtering
get_estimate - Get specific estimate details
create_estimate - Create new estimate
update_estimate - Update estimate details
delete_estimate - Delete estimate

📈 Reports (4 tools)

get_time_report - Generate time reports with filtering
get_expense_report - Generate expense reports
get_project_budget_report - Get project budget analysis
get_uninvoiced_report - Get uninvoiced time and expenses

🧪 Development

Setup

bash

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

Environment Configuration

bash

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

Testing

bash

# Run all tests
npm test

# Run with coverage
npm run test:coverage

# Run specific test suites
npm run test:unit
npm run test:integration
npm run test:contract

Building

bash

# Build for production
npm run build

# Start development server
npm run dev

📋 API Requirements

This server requires a Harvest account with API access. Users must comply with:

Harvest API Terms of Service
Harvest API Rate Limits (100 requests per 15 seconds)

🤝 Contributing

We welcome contributions! Please see our Contributing Guidelines for details.

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Make your changes with tests
Ensure all tests pass (npm test)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Harvest for providing an excellent time tracking API
Model Context Protocol team for the MCP specification
Anthropic for Claude and the MCP SDK

📞 Support

🐛 Bug Reports: GitHub Issues
💡 Feature Requests: GitHub Discussions
📖 Documentation: MCP Documentation

Made with ❤️ for the MCP community

⭐ Star this project if you find it useful!