Harvest MCP Server

🚀 Harvest MCP Server for Natural Language Time Entry

An MCP server that allows you to record Harvest time entries using natural language, including special handling for leave requests. This server makes time tracking more intuitive by understanding natural language input and automatically handling common scenarios (such as leave requests).

🚀 Quick Start

The Harvest MCP Server simplifies time tracking with natural language input. Follow the steps below to get started.

✨ Features

• 🗣️ Parse natural language time entries.
• 🏖️ Handle special leave requests (e.g., "I'm on sick leave today").
• ⏰ Configure normal working hours per day.
• 🌍 Support time zones.
• 🎯 Automatically match projects and tasks.
• 📅 Parse dates intelligently (e.g., today, yesterday).

📦 Installation

Prerequisites

• Node.js installed.
• A Harvest account.
• A personal access token obtained from Harvest Developer Tools.
• Account ID (displayed on the same page as your token).

Installation Steps

1. Install the Claude Desktop Application.
2. Clone this repository:

git clone https://github.com/adrian-dotco/harvest-mcp-server.git
cd harvest-mcp-server

3. Install dependencies and build:

npm install
npm run build

4. Run the setup script:

node build/setup.js

5. Follow the prompts to enter:
   • Your Harvest personal access token (obtained from https://id.getharvest.com/developers).
   • Your Harvest account ID.
   • Standard working hours per day (default: 7.5 hours).
   • Time zone (default: Perth, Australia).
6. Restart the Claude Desktop Application.

You're all set! Now you can use natural language time tracking in Claude.

Update

To update to the latest version:

git pull
npm install
npm run build

The setup script is configured to use your locally built server, so any updates will be automatically available after rebuilding.

💻 Usage Examples

Basic Usage

The server provides various tools to interact with Harvest:

log_time

Record time using natural language. Examples:

Regular time entry:

"Worked on Project X for 2 hours today."
"Tested on Project Y for 45 minutes yesterday."
"Attended a meeting on Project Z for 3.5 hours last Friday."

Leave requests (automatically use standard working hours):

"I'm on sick leave today."
"I'm not feeling well today."
"I'll be on vacation next week."

get_time_report

Query for time reports using natural language. Examples:

1. Time period options:

"Show the time report for last month."
"Get the summary for this week."
"Show the hours from January 1st to January 31st."
"Show the time for Q1."
"Show the hours for yesterday."

2. Report types:

• Summarize by project.
• Group by task.
• Display trend analysis.

get_help

Get a list of available commands and brief descriptions:

get_help

📚 Documentation

Configuration

You can configure the server by setting the following environment variables:

🔧 Technical Details

Tech Stack

• Backend: Node.js, Express
• Database: MongoDB
• Programming Languages: JavaScript/TypeScript

Contribution Guidelines

1. Clone the repository and install dependencies:

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

2. Create a feature branch and commit changes:

git checkout -b feature/new-feature
# Make modifications
git add .
git commit -m "Add a new feature"
git push origin feature/new-feature

3. Submit a pull request to the main branch.

📄 License

This project is licensed under the MIT License. For more details, see the LICENSE file.