Harvest MCP Server

Harvest MCP Server

An MCP (Model Context Protocol) server that provides tools for interacting with the Harvest API. This server exposes Harvest's time tracking, project management, and invoicing functionality through a standardized MCP interface.

Features

The Harvest MCP server provides access to:

• Company: Retrieve company information
• Contacts: List, create, update, and delete contacts
• Clients: Manage client records
• Time Entries: Track time, list entries, start/stop timers
• Projects: Create and manage projects
• Tasks: Define and organize tasks
• Users: List users and get current user info

Prerequisites

• Node.js 18 or higher
• A Harvest account with API access
• Harvest API credentials (Account ID and Personal Access Token)

Installation

1. Clone this repository:

2. Install dependencies:

3. Build the TypeScript code:

4. Create a .env file based on .env.example:

5. Add your Harvest credentials to .env:

Getting Harvest API Credentials

1. Log in to your Harvest account
2. Go to Settings → My Profile
3. Click on Personal Access Tokens
4. Click Create New Personal Access Token
5. Give it a name and click Create Personal Access Token
6. Copy the token (you won't be able to see it again)
7. Your Account ID is visible in the URL when logged into Harvest

Usage

Running the Server

For development:

For production:

Configuring with Claude Desktop

Add the following to your Claude Desktop configuration file:

macOS

~/Library/Application Support/Claude/claude_desktop_config.json

Windows

%APPDATA%\Claude\claude_desktop_config.json

Available Tools

Company

• harvest_get_company - Get company information

Contacts

• harvest_list_contacts - List all contacts
• harvest_get_contact - Get a specific contact
• harvest_create_contact - Create a new contact
• harvest_update_contact - Update an existing contact
• harvest_delete_contact - Delete a contact

Clients

• harvest_list_clients - List all clients
• harvest_get_client - Get a specific client
• harvest_create_client - Create a new client
• harvest_update_client - Update an existing client
• harvest_delete_client - Delete a client

Time Entries

• harvest_list_time_entries - List time entries with filters
• harvest_get_time_entry - Get a specific time entry
• harvest_create_time_entry - Create a new time entry
• harvest_update_time_entry - Update an existing time entry
• harvest_delete_time_entry - Delete a time entry
• harvest_restart_time_entry - Restart a stopped timer
• harvest_stop_time_entry - Stop a running timer

Projects

• harvest_list_projects - List all projects
• harvest_get_project - Get a specific project
• harvest_create_project - Create a new project
• harvest_update_project - Update an existing project
• harvest_delete_project - Delete a project

Tasks

• harvest_list_tasks - List all tasks
• harvest_get_task - Get a specific task
• harvest_create_task - Create a new task
• harvest_update_task - Update an existing task
• harvest_delete_task - Delete a task

Users

• harvest_list_users - List all users
• harvest_get_user - Get a specific user
• harvest_get_current_user - Get the current authenticated user

Example Usage

Once configured, you can use the tools in Claude Desktop:

Development

Project Structure

Scripts

• npm run build - Compile TypeScript to JavaScript
• npm run dev - Run in development mode with hot reload
• npm start - Run the compiled server

Error Handling

The server includes comprehensive error handling:

• Invalid API credentials will return authentication errors
• Rate limiting is respected per Harvest's API guidelines
• Network errors are caught and reported clearly
• Invalid parameters are validated before API calls

License

MIT

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Submit a pull request

Support

For issues with:

• This MCP server: Open an issue in this repository
• Harvest API: Consult the Harvest API documentation
• MCP protocol: See the MCP documentation