README.md•4.25 kB
# Harvest MCP Server
A Model Context Protocol (MCP) server that provides integration with the [Harvest API v2](https://help.getharvest.com/api-v2/).
## Features
This MCP server provides tools for interacting with Harvest time tracking data:
### Time Entry Management
- List time entries with filters
- Create new time entries
- Update existing time entries
- Delete time entries
### Project & Task Management
- List and view projects
- List available tasks
### User & Client Management
- Get current user information
- List all users
- List all clients
### Reporting
- Generate time reports for date ranges
### Assignments
- List project assignments
- List task assignments for projects
## Installation
```bash
# Clone the repository
git clone <repository-url>
cd harvest-mcp
# Install dependencies
npm install
# Build the project
npm run build
```
## Configuration
1. Copy the environment template:
```bash
cp .env.example .env
```
2. Edit `.env` and add your Harvest credentials:
```
HARVEST_ACCOUNT_ID=your_account_id
HARVEST_ACCESS_TOKEN=your_access_token
```
To get your Harvest credentials:
- Log in to your Harvest account
- Go to [Developers](https://id.getharvest.com/developers)
- Create a new personal access token
- Note your Account ID
## Development
```bash
# Run in development mode with hot reload
npm run dev
# Build the project
npm run build
# Run the built server
npm start
```
## Testing
The project includes comprehensive tests to verify integration with the Harvest API:
```bash
# Run unit tests
npm test
# Run unit tests in watch mode
npm run test:watch
# Run integration tests (requires valid .env setup)
npm run test:integration
```
### Integration Tests
The integration tests connect to your actual Harvest account and perform read-only operations to verify the MCP server works correctly. These tests:
- Connect to the MCP server via stdio transport
- Test all 14 available tools
- Verify proper data structure responses
- Test error handling for invalid inputs
- Use actual Harvest API data (read-only operations only)
**Requirements for integration tests:**
- Valid `.env` file with `HARVEST_ACCOUNT_ID` and `HARVEST_ACCESS_TOKEN`
- Active Harvest account with some data (projects, time entries, etc.)
- Network access to Harvest API
## Using with Claude Desktop
Add the following to your Claude Desktop configuration file:
```json
{
"mcpServers": {
"harvest": {
"command": "node",
"args": ["/path/to/harvest-mcp/dist/index.js"],
"env": {
"HARVEST_ACCOUNT_ID": "your_account_id",
"HARVEST_ACCESS_TOKEN": "your_access_token"
}
}
}
}
```
## Available Tools
| Tool | Description |
|------|-------------|
| `harvest_list_time_entries` | List time entries with optional filters |
| `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_timer` | Restart a stopped time entry timer |
| `harvest_stop_timer` | Stop a running time entry timer |
| `harvest_list_projects` | List all projects |
| `harvest_get_project` | Get details of a specific project |
| `harvest_list_tasks` | List all tasks |
| `harvest_get_current_user` | Get information about the authenticated user |
| `harvest_list_users` | List all users in the account |
| `harvest_list_clients` | List all clients |
| `harvest_time_report` | Get time report for a date range |
| `harvest_list_project_assignments` | List project assignments for the current user |
| `harvest_list_task_assignments` | List task assignments for a project |
## Tool Parameters
### Time Entry Tools
**harvest_list_time_entries**
- `user_id` (string): Filter by user ID
- `project_id` (string): Filter by project ID
- `from` (string): Start date (YYYY-MM-DD)
- `to` (string): End date (YYYY-MM-DD)
- `page` (number): Page number
- `per_page` (number): Results per page (max 100)
**harvest_create_time_entry**
- `project_id` (string, required): Project ID
- `task_id` (string, required): Task ID
- `spent_date` (string, required): Date of the entry (YYYY-MM-DD)
- `hours` (number): Hours worked
- `notes` (string): Notes for the time entry
## License
MIT