🕐 Harvest MCP Server

Connect your AI assistants to Harvest for seamless time tracking. Get started in minutes with Claude Desktop or Cursor IDE.

Ready to Use

🚀 Quick Setup (3 Steps)

Get Your Server API Key from Your System Admin

Contact your system administrator or the person who deployed this MCP server to get the API key for access control.

Get Your Harvest Credentials

• Go to Harvest Developers
• Create a Personal Access Token
• Copy the Token and Account ID

Configure Your AI Assistant

Choose your preferred AI assistant below and follow the configuration steps.

🔗 AI Assistant Configuration

🤖Claude Desktop

Add this configuration to your claude_desktop_config.json file:

Loading configuration...

📝 How to access the configuration file:

Open Claude Desktop
Go to Menu → Claude → Settings
Click on the Developer tab
Click Edit Config button
This will open the file in your default text editor

Alternative: Manual file locations:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

⚡Cursor IDE

Add this configuration to your ~/.cursor/mcp.json file:

Loading configuration...

⚠️ Important for Cursor:

Cursor requires headers without spaces after the colon (e.g., "X-API-Key:value" not "X-API-Key: value"). The configuration above is formatted correctly for Cursor.

🔐 Important: Replace Your Credentials

In the configuration above, replace these placeholders with your actual credentials:

• your_server_api_key → Server API key for access control
• your_harvest_personal_access_token → Your Personal Access Token from Harvest
• your_harvest_account_id → Your Harvest Account ID

⚠️ Keep these credentials secure and never commit them to version control.

✨ What You Can Do

⏱️ Time Management

• Create and update time entries
• Start and stop timers
• View recent time entries
• Delete time entries

📊 Project Management

• Create new projects
• Update project settings
• Archive/activate projects
• View your recent projects & tasks
• View project details
• Manage user assignments
• Set project manager roles
• Access user information

📈 Reports & Analytics

• Time reports by clients
• Time reports by projects
• Time reports by tasks
• Time reports by team members
• Project budget reports
• Budget vs actual spending
• Monthly billable totals 🆕
• Year-to-date analytics 🆕
• Quarterly reports 🆕
• Automatic pagination for all reports 🔧

💬 Feedback & Support

• Submit bug reports
• Request new features
• Send general feedback
• Check service health

💡 Example Commands

Time Tracking:

• "Create a time entry for 2 hours on project X with notes about API work"
• "Start a timer for my meeting with the client"
• "Show me my time entries from this week"

Project Management:

• "Create a new project for client ABC with hourly billing"
• "Update project XYZ to set the budget to $10,000"
• "Archive the old marketing project"
• "Show me my recent projects and tasks"
• "Assign John to the website project as project manager"

Reports & Analytics:

• "Show me time reports by client for this month"
• "Generate a project budget report for active projects"
• "Get team time report from January 1st to 31st"
• "Show task breakdown for the last quarter"
• "Get monthly billable totals for 2024-01" 🆕
• "Show year-to-date totals with breakdown by user" 🆕
• "Generate Q1 2024 quarterly report" 🆕

Information & Feedback:

• "What projects have I been working on recently?"
• "Submit feedback: The timer sometimes doesn't start properly"
• "Report a bug with high priority about time entry deletion"

🚀 New: Enhanced Reporting with Auto-Pagination

Our latest update includes powerful new reporting tools that automatically handle large datasets and provide comprehensive totals:

Monthly Totals:

• Total billable hours for any month
• Multi-currency billable amounts
• Team utilization rates
• Optional per-user breakdown

Auto-Pagination:

• Handles unlimited team members
• Processes all data pages automatically
• Progress tracking for large datasets
• Intelligent caching for performance

Advanced Analytics:

• Year-to-date summaries
• Quarterly comparisons
• Utilization rate calculations
• Multi-currency support

🎯 New: My Recent Projects & Tasks

Get personalized insights into your recent work patterns with our new "My Recent Projects" resource that analyzes your time entries from the last 2 weeks:

📊 Smart Analysis:

• Projects you've actually worked on (not just "active")
• Tasks within each project with usage statistics
• Last used dates and total hours tracked
• Sorted by most recent activity

🔗 Interactive Features:

• User-specific caching for fast performance
• Dynamic project resource templates
• Seamless integration with Claude Desktop
• Compatible with Vercel deployment platform

💡 Example Output:

Your Recent Projects & Tasks (last 2 weeks, 15 time entries):

• Website Redesign (ID: 123) - Client: Acme Corp
  └── Design (last used: 2024-01-15) (8.5h)
  └── Development (last used: 2024-01-14) (12.0h)

• Mobile App (ID: 456) - Client: Tech Startup
  └── Backend API (last used: 2024-01-13) (6.0h)

🔧 Recent Fix: Reports Now Use Auto-Pagination

We've just fixed an issue with the basic report tools where pagination parameters were causing schema validation errors. All report tools now use automatic pagination behind the scenes:

✅ Fixed Tools:

• get_time_report_clients - No more pagination errors
• get_time_report_projects - Complete datasets automatically
• get_time_report_tasks - All results in one response
• get_time_report_team - Full team data
• get_project_budget_report - All projects included

🎯 Benefits:

• No more "null pagination" errors
• Complete datasets without manual paging
• Consistent with monthly totals tools
• Better user experience
• Automatic caching for performance

🛠️ Available Tools

⚠️ Note: Tool availability and functionality depend on your Harvest account permissions. Some tools may be restricted based on your user role (admin, project manager, or team member) and account-level settings. Contact your Harvest administrator if you need additional permissions.

Time Entry Tools:

• create_time_entry - Create new time entries
• update_time_entry - Update existing entries
• delete_time_entry - Delete time entries
• start_timer - Start a new timer
• stop_timer - Stop running timer

Project Management Tools:

• create_project - Create new projects
• update_project - Update project settings
• delete_project - Delete projects (with confirmation)
• archive_project - Archive projects safely
• activate_project - Reactivate archived projects

Project Assignment Tools:

• get_my_project_assignments - List your assigned projects
• create_user_assignment - Assign users to projects
• update_user_assignment - Update assignment settings
• set_project_manager - Grant/revoke manager roles
• delete_user_assignment - Remove assignments

Reports & Analytics Tools:

• get_time_report_clients - Time by clients 🔧
• get_time_report_projects - Time by projects 🔧
• get_time_report_tasks - Time by tasks 🔧
• get_time_report_team - Time by team members 🔧
• get_project_budget_report - Budget analysis 🔧
• get_monthly_billable_totals - Monthly totals with auto-pagination 🆕
• get_year_to_date_totals - YTD analytics 🆕
• get_quarterly_totals - Quarterly reports 🆕

Query & Support Tools:

• get_time_entries - View time entries
• get_projects - Browse projects
• get_current_user - User information
• submit_feedback - Send feedback to ClickUp
• check_feedback_service - Health check

🔧 = Recently Fixed: These tools now use automatic pagination and no longer require manual page parameters. They return complete datasets automatically.

🔧 Need Help?

After updating configuration:

Restart Claude Desktop or Cursor IDE to load the new settings.

Need the server API key?

Contact your system administrator or the person who deployed this MCP server for the API key.

For developers:

Check the README.md for development setup, deployment instructions, and advanced configuration options.