Metadata-Version: 2.4
Name: harvest-mcp
Version: 0.1.1
Summary: Harvest MCP Server for managing Harvest via the Model Context Protocol
Author-email: Barie <support@barie.ai>
License: MIT
Keywords: harvest,mcp,model-context-protocol,project-management,time-tracking
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Requires-Dist: httpx>=0.28.1
Requires-Dist: mcp>=1.4.1
Description-Content-Type: text/markdown

# Harvest MCP Server

A Model Context Protocol (MCP) server for interacting with Harvest time tracking and project management APIs.

The PyPI package and the command you run are the same name: **`harvest-mcp`**.

## Install

```bash
pip install harvest-mcp
```

## Run (PyPI — no `--from`)

```bash
uvx harvest-mcp --help

uvx harvest-mcp \
  --account-id "<harvest_account_id>" \
  --api-key "<harvest_api_key>" \
  --read-only "false"
```

`uvx` downloads the package if needed, installs it in an isolated environment, and runs the `harvest-mcp` CLI.

## Run (editable / local checkout)

```bash
pip install -e .
harvest-mcp --help
```

## Run with `python -m` (package already in that interpreter)

```bash
python -m harvest_mcp_server \
  --account-id "<harvest_account_id>" \
  --api-key "<harvest_api_key>" \
  --read-only "false"
```

The import path uses underscores (`harvest_mcp_server`); the user-facing CLI is `harvest-mcp`.

### Required arguments

- `--account-id`: Harvest account ID
- `--api-key`: Harvest API key

### Optional arguments

- `--read-only`: Enable read-only mode (`true`/`false`), default `false`

## Features

- Users (list, detail)
- Time entries (list, create, start/stop timers, details, unsubmitted)
- Projects, clients, and tasks lookup
- Estimates lifecycle (list/detail/lookup/create/update/state-change/send/delete)
- Optional read-only mode for safe operation

## MCP configuration (recommended)

Use **`uvx`** and a single tool name — no `--from`** when pulling from PyPI:

```json
{
  "mcpServers": {
    "harvest-mcp": {
      "command": "uvx",
      "args": [
        "harvest-mcp",
        "--account-id",
        "YOUR_HARVEST_ACCOUNT_ID",
        "--api-key",
        "YOUR_HARVEST_API_KEY",
        "--read-only",
        "true"
      ]
    }
  }
}
```

If `uvx` is not on `PATH`, set `"command"` to the full path of the `uvx` binary (for example `~/.local/bin/uvx` on Linux).

### Local wheel (offline / pre-release)

Only when you are not using PyPI, point `uvx` at a wheel file. The tool name at the end must still be **`harvest-mcp`** (the console script):

```json
"args": [
  "--from",
  "/absolute/path/to/harvest_mcp-0.1.1-py3-none-any.whl",
  "harvest-mcp",
  "--account-id",
  "YOUR_HARVEST_ACCOUNT_ID",
  "--api-key",
  "YOUR_HARVEST_API_KEY"
]
```

### `python -m` (package installed in the same environment as the MCP host)

```json
{
  "mcpServers": {
    "harvest-mcp": {
      "command": "python",
      "args": [
        "-m",
        "harvest_mcp_server",
        "--account-id",
        "YOUR_HARVEST_ACCOUNT_ID",
        "--api-key",
        "YOUR_HARVEST_API_KEY",
        "--read-only",
        "true"
      ]
    }
  }
}
```

## Development

From the `harvest-mcp-server` directory:

```bash
pip install -e .
harvest-mcp --help
```

Build a wheel:

```bash
python -m build
```
