mcp-server-harvest-time-tracking

A Model Context Protocol (MCP) server implementation for Harvest, enabling seamless integration with MCP clients. This project provides a standardized way to interact with Harvest through the Model Context Protocol. This is essentially a wrapper for the Harvest API in MCP format.

About

This project implements a Model Context Protocol server that wraps Harvest's REST API, allowing MCP clients to interact with Harvest in a standardized way. It provides access to Harvest's time tracking, client, project, and reporting features.

Feature Implementation Status

Feature	Status
Time Entries
List Time Entries	✅
Get Time Entry	✅
Create Time Entry (Duration)	✅
Create Time Entry (Start/End)	✅
Update Time Entry	✅
Delete Time Entry	✅
Delete Time Entry External Reference	✅
Restart Time Entry	✅
Stop Time Entry	✅
Clients
List Clients	✅
Get Client	✅
Create Client	✅
Update Client	✅
Delete Client	✅
Projects
List Projects	✅
Get Project	✅
Create Project	✅
Update Project	✅
Delete Project	✅
Reports
Get Clients Time Report	✅
Get Projects Time Report	✅
Get Tasks Time Report	✅
Get Team Time Report	✅

Setup

Dependencies

This project depends on the following packages:

mcp: Model Context Protocol implementation
requests: For making HTTP requests to the Harvest API
python-dotenv: For loading environment variables

Environment Variables

Set the following environment variables:

HARVEST_ACCOUNT_ID=<your-harvest-account-id>
HARVEST_ACCESS_TOKEN=<your-harvest-access-token>

You can obtain these credentials from your Harvest account settings or by creating a new OAuth2 application in Harvest.

Installation

Clone the repository:

git clone https://github.com/your-username/mcp-server-harvest-time-tracking.git
cd mcp-server-harvest-time-tracking

Set up a virtual environment and install dependencies:

make setup

Usage with Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "mcp-server-harvest-time-tracking": {
      "command": "python",
      "args": ["-m", "src.server"],
      "cwd": "/path/to/mcp-server-harvest-time-tracking",
      "env": {
        "HARVEST_ACCOUNT_ID": "your-harvest-account-id",
        "HARVEST_ACCESS_TOKEN": "your-harvest-access-token"
      }
    }
  }
}

Replace /path/to/mcp-server-harvest-time-tracking with the actual path where you've cloned the repository.

Manual Execution

You can run the server manually:

make run

Options in the Makefile:

setup: Set up the virtual environment and install dependencies
run: Run the server in stdio mode (default)
test: Run tests
clean: Clean up temporary files and virtual environment

API Usage Examples

Time Entries

# List time entries
time_entries = list_time_entries(user_id=123, from_date="2023-01-01")

# Create a time entry with duration
entry = create_time_entry_duration(
    project_id=456,
    task_id=789,
    spent_date="2023-01-15",
    hours=2.5,
    notes="Working on documentation"
)

# Stop a running time entry
result = stop_time_entry(time_entry_id=12345)

Projects

# List all active projects
projects = list_projects(is_active=True)

# Get project details
project = get_project(project_id=456)

# Create a new project
new_project = create_project(
    client_id=123,
    name="New Website Development",
    code="NWD-2023",
    is_billable=True
)

Reports

# Get time report for all projects
report = get_projects_time_report(
    from_date="2023-01-01",
    to_date="2023-01-31"
)

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

License

MIT License

Harvest Time Tracking MCP Server

Integrations