ianaleck/harvest-mcp-server
Harvest time tracking integration with 40+ tools for managing time entries, projects, clients, tasks, and generating time reports via the Harvest API v2
Ask AI about ianaleck/harvest-mcp-server
Powered by Claude Β· Grounded in docs
I know everything about ianaleck/harvest-mcp-server. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
πΎ 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
# 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):
{
"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 filteringget_time_entry- Get specific time entry detailscreate_time_entry- Create new time entryupdate_time_entry- Update existing time entrydelete_time_entry- Delete time entrystart_timer- Start a timer for a taskstop_timer- Stop running timerrestart_timer- Restart a previous time entry
ποΈ Projects (7 tools)
list_projects- List all projects with filteringget_project- Get specific project detailscreate_project- Create new projectupdate_project- Update project detailsdelete_project- Delete projectlist_project_task_assignments- List task assignments for projectcreate_project_task_assignment- Assign task to projectupdate_project_task_assignment- Update task assignmentdelete_project_task_assignment- Remove task assignment
π Tasks (5 tools)
list_tasks- List all tasksget_task- Get specific task detailscreate_task- Create new taskupdate_task- Update task detailsdelete_task- Delete task
π’ Clients (5 tools)
list_clients- List all clientsget_client- Get specific client detailscreate_client- Create new clientupdate_client- Update client detailsdelete_client- Delete client
π€ Users (6 tools)
list_users- List all users in accountget_user- Get specific user detailsget_current_user- Get current authenticated usercreate_user- Create new userupdate_user- Update user detailsdelete_user- Delete user
πΈ Expenses (6 tools)
list_expenses- List expenses with filteringget_expense- Get specific expense detailscreate_expense- Create new expenseupdate_expense- Update expense detailsdelete_expense- Delete expenselist_expense_categories- List all expense categories
π§Ύ Invoices (5 tools)
list_invoices- List invoices with filteringget_invoice- Get specific invoice detailscreate_invoice- Create new invoiceupdate_invoice- Update invoice detailsdelete_invoice- Delete invoice
π Estimates (5 tools)
list_estimates- List estimates with filteringget_estimate- Get specific estimate detailscreate_estimate- Create new estimateupdate_estimate- Update estimate detailsdelete_estimate- Delete estimate
π Reports (4 tools)
get_time_report- Generate time reports with filteringget_expense_report- Generate expense reportsget_project_budget_report- Get project budget analysisget_uninvoiced_report- Get uninvoiced time and expenses
π§ͺ Development
Setup
git clone https://github.com/ianaleck/harvest-mcp-server.git
cd harvest-mcp-server
npm install
Environment Configuration
cp .env.example .env
# Edit .env with your Harvest API credentials
Testing
# 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
# 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!
