@mnicole-dev/harvest-mcp-server 1.0.0

package/README.md

@@ -0,0 +1,222 @@
+# @mnicole-dev/harvest-mcp-server
+
+A [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server for the [Harvest](https://www.getharvest.com) time tracking API (v2). Manage time entries, projects, tasks, clients, users, and timers from any MCP-compatible client.
+
+## Features
+
+**37 tools** covering the full Harvest API v2:
+
+### Time Entries (8 tools)
+| Tool | Description |
+|------|-------------|
+| `list-time-entries` | List entries with filters (date range, project, user, task, billed, running) |
+| `get-time-entry` | Get a single time entry by ID |
+| `create-time-entry` | Log hours for a project/task on a date (duration or start/end time) |
+| `update-time-entry` | Update hours, notes, date, project, or task |
+| `delete-time-entry` | Delete a time entry |
+| `start-timer` | Start a running timer for a project/task |
+| `stop-timer` | Stop a running timer |
+| `restart-timer` | Restart a stopped timer |
+
+### Projects (4 tools)
+| Tool | Description |
+|------|-------------|
+| `list-projects` | List all projects (filter by client, active status) |
+| `get-project` | Get project details (budget, rates, dates, notes) |
+| `create-project` | Create a project with billing, budget, and fee settings |
+| `update-project` | Update project settings |
+| `delete-project` | Delete a project |
+
+### Tasks (4 tools)
+| Tool | Description |
+|------|-------------|
+| `list-tasks` | List all tasks in the account |
+| `create-task` | Create a new task |
+| `update-task` | Update a task |
+| `delete-task` | Delete a task |
+
+### Task Assignments (4 tools)
+| Tool | Description |
+|------|-------------|
+| `list-project-task-assignments` | List which tasks are assigned to a project |
+| `create-task-assignment` | Assign a task to a project |
+| `update-task-assignment` | Update task assignment (billable, rate, budget) |
+| `delete-task-assignment` | Remove a task from a project |
+
+### User Assignments (4 tools)
+| Tool | Description |
+|------|-------------|
+| `list-project-user-assignments` | List which users are assigned to a project |
+| `create-user-assignment` | Assign a user to a project |
+| `update-user-assignment` | Update assignment (PM role, rate, budget) |
+| `delete-user-assignment` | Remove a user from a project |
+
+### Users (5 tools)
+| Tool | Description |
+|------|-------------|
+| `get-me` | Get the authenticated user's profile |
+| `list-users` | List all users in the account |
+| `get-user` | Get a user's full profile |
+| `create-user` | Create a new user |
+| `update-user` | Update a user (or archive with isActive: false) |
+| `delete-user` | Delete a user (only if no time entries/expenses) |
+
+### Clients (4 tools)
+| Tool | Description |
+|------|-------------|
+| `list-clients` | List all clients |
+| `get-client` | Get a client's details |
+| `create-client` | Create a new client |
+| `update-client` | Update a client |
+| `delete-client` | Delete a client |
+
+### Company (1 tool)
+| Tool | Description |
+|------|-------------|
+| `get-company` | Get company settings (plan, capacity, format, currency) |
+
+## Requirements
+
+- Node.js 18+
+- A Harvest account with API access
+- A [personal access token](https://id.getharvest.com/developers) and your account ID
+
+## Installation
+
+```bash
+npm install -g @mnicole-dev/harvest-mcp-server
+```
+
+Or run directly with `npx`:
+
+```bash
+npx @mnicole-dev/harvest-mcp-server
+```
+
+## Configuration
+
+Set these environment variables:
+
+```bash
+export HARVEST_ACCESS_TOKEN=your-token-here
+export HARVEST_ACCOUNT_ID=your-account-id
+```
+
+### Claude Code
+
+Add to your `~/.claude.json`:
+
+```json
+{
+  "mcpServers": {
+    "harvest": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@mnicole-dev/harvest-mcp-server"],
+      "env": {
+        "HARVEST_ACCESS_TOKEN": "your-token-here",
+        "HARVEST_ACCOUNT_ID": "your-account-id"
+      }
+    }
+  }
+}
+```
+
+### Claude Desktop
+
+Add to your config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
+
+```json
+{
+  "mcpServers": {
+    "harvest": {
+      "command": "npx",
+      "args": ["-y", "@mnicole-dev/harvest-mcp-server"],
+      "env": {
+        "HARVEST_ACCESS_TOKEN": "your-token-here",
+        "HARVEST_ACCOUNT_ID": "your-account-id"
+      }
+    }
+  }
+}
+```
+
+### Cursor / Windsurf / other MCP clients
+
+Use the stdio transport with `npx -y @mnicole-dev/harvest-mcp-server` as the command and pass both environment variables.
+
+## Examples
+
+### Log time
+
+```
+> Log 4 hours on project 12345, task 67890 for today with notes "API development"
+```
+
+Calls `create-time-entry` with:
+```json
+{
+  "projectId": 12345,
+  "taskId": 67890,
+  "spentDate": "2026-03-17",
+  "hours": 4,
+  "notes": "API development"
+}
+```
+
+### Start a timer
+
+```
+> Start a timer for project 12345, task 67890
+```
+
+Calls `start-timer` — creates a running time entry. Use `stop-timer` to stop it.
+
+### View this week's entries
+
+```
+> Show me all time entries from Monday to Friday this week
+```
+
+Calls `list-time-entries` with `from` and `to` date parameters.
+
+### Create a project
+
+```
+> Create a new billable project "Website Redesign" for client 123, billed by tasks, budget 100 hours
+```
+
+Calls `create-project` with:
+```json
+{
+  "clientId": 123,
+  "name": "Website Redesign",
+  "isBillable": true,
+  "billBy": "Tasks",
+  "budgetBy": "project",
+  "budget": 100
+}
+```
+
+## How it works
+
+1. The MCP client sends a tool call to the server via stdio
+2. The server authenticates with the Harvest API v2 using your personal access token
+3. The request is forwarded to `https://api.harvestapp.com/api/v2/`
+4. The response is formatted as human-readable text and returned
+
+All requests include the required `Authorization`, `Harvest-Account-Id`, and `User-Agent` headers.
+
+## Development
+
+```bash
+git clone https://github.com/mnicole-dev/harvest-mcp-server.git
+cd harvest-mcp-server
+pnpm install
+pnpm dev          # Run with tsx (requires HARVEST_ACCESS_TOKEN + HARVEST_ACCOUNT_ID)
+pnpm build        # Build to dist/
+```
+
+## License
+
+MIT

package/dist/index.js

@@ -0,0 +1,941 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+var API_BASE = "https://api.harvestapp.com/api/v2";
+function getCredentials() {
+  const token = process.env["HARVEST_ACCESS_TOKEN"];
+  const accountId = process.env["HARVEST_ACCOUNT_ID"];
+  if (!token) throw new Error("HARVEST_ACCESS_TOKEN environment variable is required");
+  if (!accountId) throw new Error("HARVEST_ACCOUNT_ID environment variable is required");
+  return { token, accountId };
+}
+async function harvestFetch(path, options) {
+  const { token, accountId } = getCredentials();
+  let url = `${API_BASE}${path}`;
+  if (options?.params) {
+    const qs = new URLSearchParams(options.params).toString();
+    if (qs) url += `?${qs}`;
+  }
+  const { params: _, ...fetchOptions } = options ?? {};
+  return fetch(url, {
+    ...fetchOptions,
+    headers: {
+      Authorization: `Bearer ${token}`,
+      "Harvest-Account-Id": accountId,
+      "User-Agent": "harvest-mcp-server",
+      "Content-Type": "application/json",
+      ...fetchOptions?.headers
+    }
+  });
+}
+async function assertOk(resp, action) {
+  if (resp.ok) {
+    if (resp.status === 200 || resp.status === 201) return resp.json();
+    return {};
+  }
+  const body = await resp.text();
+  throw new Error(`${action} failed (${resp.status}): ${body}`);
+}
+function textResult(text) {
+  return { content: [{ type: "text", text }] };
+}
+function today() {
+  return (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+}
+var server = new McpServer({
+  name: "harvest-mcp-server",
+  version: "1.0.0"
+});
+server.tool(
+  "list-time-entries",
+  "List time entries with optional filters (date range, project, user, task). Returns the most recent entries.",
+  {
+    from: z.string().optional().describe("Start date (YYYY-MM-DD). Defaults to today."),
+    to: z.string().optional().describe("End date (YYYY-MM-DD). Defaults to today."),
+    projectId: z.number().optional().describe("Filter by project ID"),
+    taskId: z.number().optional().describe("Filter by task ID"),
+    userId: z.number().optional().describe("Filter by user ID"),
+    isBilled: z.boolean().optional().describe("Filter by invoiced status"),
+    isRunning: z.boolean().optional().describe("Filter by running timer status"),
+    perPage: z.number().min(1).max(2e3).default(100).describe("Results per page")
+  },
+  async (params) => {
+    const qp = {};
+    qp["from"] = params.from ?? today();
+    qp["to"] = params.to ?? today();
+    if (params.projectId) qp["project_id"] = String(params.projectId);
+    if (params.taskId) qp["task_id"] = String(params.taskId);
+    if (params.userId) qp["user_id"] = String(params.userId);
+    if (params.isBilled !== void 0) qp["is_billed"] = String(params.isBilled);
+    if (params.isRunning !== void 0) qp["is_running"] = String(params.isRunning);
+    qp["per_page"] = String(params.perPage);
+    const resp = await harvestFetch("/time_entries", { params: qp });
+    const data = await assertOk(resp, "List time entries");
+    if (data.time_entries.length === 0) return textResult("No time entries found.");
+    const lines = data.time_entries.map((e) => {
+      const running = e.is_running ? " [RUNNING]" : "";
+      const notes = e.notes ? ` \u2014 ${e.notes}` : "";
+      return `- **${e.spent_date}** | ${e.hours}h | ${e.project.name} > ${e.task.name}${notes}${running} (id: ${e.id})`;
+    });
+    lines.push(`
+_Total: ${data.total_entries} entries_`);
+    return textResult(lines.join("\n"));
+  }
+);
+server.tool(
+  "get-time-entry",
+  "Retrieve a single time entry by ID.",
+  {
+    timeEntryId: z.number().describe("Time entry ID")
+  },
+  async ({ timeEntryId }) => {
+    const resp = await harvestFetch(`/time_entries/${timeEntryId}`);
+    const e = await assertOk(resp, "Get time entry");
+    const running = e.is_running ? " [RUNNING]" : "";
+    const notes = e.notes ? `
+Notes: ${e.notes}` : "";
+    const times = e.started_time && e.ended_time ? `
+Time: ${e.started_time} \u2192 ${e.ended_time}` : "";
+    return textResult(
+      `**${e.project.name} > ${e.task.name}**
+Date: ${e.spent_date}
+Hours: ${e.hours}h${running}${times}${notes}
+User: ${e.user.name}
+ID: ${e.id}`
+    );
+  }
+);
+server.tool(
+  "create-time-entry",
+  "Create a new time entry (log hours for a project/task on a date).",
+  {
+    projectId: z.number().describe("Project ID"),
+    taskId: z.number().describe("Task ID"),
+    spentDate: z.string().default("today").describe('Date (YYYY-MM-DD or "today")'),
+    hours: z.number().optional().describe("Hours to log. Omit to start a running timer."),
+    notes: z.string().optional().describe("Notes/description"),
+    startedTime: z.string().optional().describe('Start time (e.g. "8:00am"). Use instead of hours for time-based tracking.'),
+    endedTime: z.string().optional().describe('End time (e.g. "5:00pm"). Omit to start a running timer.'),
+    userId: z.number().optional().describe("User ID (defaults to authenticated user)")
+  },
+  async (params) => {
+    const body = {
+      project_id: params.projectId,
+      task_id: params.taskId,
+      spent_date: params.spentDate === "today" ? today() : params.spentDate
+    };
+    if (params.hours !== void 0) body["hours"] = params.hours;
+    if (params.notes) body["notes"] = params.notes;
+    if (params.startedTime) body["started_time"] = params.startedTime;
+    if (params.endedTime) body["ended_time"] = params.endedTime;
+    if (params.userId) body["user_id"] = params.userId;
+    const resp = await harvestFetch("/time_entries", {
+      method: "POST",
+      body: JSON.stringify(body)
+    });
+    const e = await assertOk(resp, "Create time entry");
+    const running = e.is_running ? " (timer running)" : "";
+    return textResult(
+      `Time entry created!
+- **${e.project.name} > ${e.task.name}**
+- Date: ${e.spent_date}
+- Hours: ${e.hours}h${running}
+- ID: ${e.id}`
+    );
+  }
+);
+server.tool(
+  "update-time-entry",
+  "Update an existing time entry (change hours, notes, date, project, or task).",
+  {
+    timeEntryId: z.number().describe("Time entry ID"),
+    projectId: z.number().optional().describe("New project ID"),
+    taskId: z.number().optional().describe("New task ID"),
+    spentDate: z.string().optional().describe("New date (YYYY-MM-DD)"),
+    hours: z.number().optional().describe("New hours"),
+    notes: z.string().optional().describe("New notes"),
+    startedTime: z.string().optional().describe("New start time"),
+    endedTime: z.string().optional().describe("New end time")
+  },
+  async (params) => {
+    const body = {};
+    if (params.projectId) body["project_id"] = params.projectId;
+    if (params.taskId) body["task_id"] = params.taskId;
+    if (params.spentDate) body["spent_date"] = params.spentDate;
+    if (params.hours !== void 0) body["hours"] = params.hours;
+    if (params.notes !== void 0) body["notes"] = params.notes;
+    if (params.startedTime) body["started_time"] = params.startedTime;
+    if (params.endedTime) body["ended_time"] = params.endedTime;
+    const resp = await harvestFetch(`/time_entries/${params.timeEntryId}`, {
+      method: "PATCH",
+      body: JSON.stringify(body)
+    });
+    const e = await assertOk(resp, "Update time entry");
+    return textResult(
+      `Time entry updated!
+- **${e.project.name} > ${e.task.name}**
+- Date: ${e.spent_date}
+- Hours: ${e.hours}h
+- ID: ${e.id}`
+    );
+  }
+);
+server.tool(
+  "delete-time-entry",
+  "Delete a time entry by ID.",
+  {
+    timeEntryId: z.number().describe("Time entry ID")
+  },
+  async ({ timeEntryId }) => {
+    const resp = await harvestFetch(`/time_entries/${timeEntryId}`, {
+      method: "DELETE"
+    });
+    if (!resp.ok) {
+      const body = await resp.text();
+      throw new Error(`Delete failed (${resp.status}): ${body}`);
+    }
+    return textResult(`Time entry ${timeEntryId} deleted.`);
+  }
+);
+server.tool(
+  "start-timer",
+  "Start a timer for a project/task. Creates a new running time entry.",
+  {
+    projectId: z.number().describe("Project ID"),
+    taskId: z.number().describe("Task ID"),
+    notes: z.string().optional().describe("Notes/description")
+  },
+  async (params) => {
+    const body = {
+      project_id: params.projectId,
+      task_id: params.taskId,
+      spent_date: today()
+    };
+    if (params.notes) body["notes"] = params.notes;
+    const resp = await harvestFetch("/time_entries", {
+      method: "POST",
+      body: JSON.stringify(body)
+    });
+    const e = await assertOk(resp, "Start timer");
+    return textResult(
+      `Timer started!
+- **${e.project.name} > ${e.task.name}**
+- ID: ${e.id}`
+    );
+  }
+);
+server.tool(
+  "stop-timer",
+  "Stop a running time entry timer.",
+  {
+    timeEntryId: z.number().describe("Time entry ID of the running timer")
+  },
+  async ({ timeEntryId }) => {
+    const resp = await harvestFetch(`/time_entries/${timeEntryId}/stop`, {
+      method: "PATCH"
+    });
+    const e = await assertOk(resp, "Stop timer");
+    return textResult(
+      `Timer stopped!
+- **${e.project.name} > ${e.task.name}**
+- Hours: ${e.hours}h
+- ID: ${e.id}`
+    );
+  }
+);
+server.tool(
+  "restart-timer",
+  "Restart a previously stopped time entry timer.",
+  {
+    timeEntryId: z.number().describe("Time entry ID to restart")
+  },
+  async ({ timeEntryId }) => {
+    const resp = await harvestFetch(`/time_entries/${timeEntryId}/restart`, {
+      method: "PATCH"
+    });
+    const e = await assertOk(resp, "Restart timer");
+    return textResult(
+      `Timer restarted!
+- **${e.project.name} > ${e.task.name}**
+- ID: ${e.id}`
+    );
+  }
+);
+server.tool(
+  "list-projects",
+  "List all projects, optionally filtered by client or active status.",
+  {
+    isActive: z.boolean().optional().describe("Filter by active status"),
+    clientId: z.number().optional().describe("Filter by client ID"),
+    perPage: z.number().min(1).max(2e3).default(100).describe("Results per page")
+  },
+  async (params) => {
+    const qp = {};
+    if (params.isActive !== void 0) qp["is_active"] = String(params.isActive);
+    if (params.clientId) qp["client_id"] = String(params.clientId);
+    qp["per_page"] = String(params.perPage);
+    const resp = await harvestFetch("/projects", { params: qp });
+    const data = await assertOk(resp, "List projects");
+    if (data.projects.length === 0) return textResult("No projects found.");
+    const lines = data.projects.map((p) => {
+      const budget = p.budget ? ` | Budget: ${p.budget}h` : "";
+      const code = p.code ? ` (${p.code})` : "";
+      const active = p.is_active ? "" : " [INACTIVE]";
+      return `- **${p.name}**${code} \u2014 ${p.client.name}${budget}${active} (id: ${p.id})`;
+    });
+    lines.push(`
+_Total: ${data.total_entries} projects_`);
+    return textResult(lines.join("\n"));
+  }
+);
+server.tool(
+  "get-project",
+  "Retrieve a single project by ID with full details.",
+  {
+    projectId: z.number().describe("Project ID")
+  },
+  async ({ projectId }) => {
+    const resp = await harvestFetch(`/projects/${projectId}`);
+    const p = await assertOk(resp, "Get project");
+    const notes = p.notes ? `
+Notes: ${p.notes}` : "";
+    const dates = p.starts_on || p.ends_on ? `
+Dates: ${p.starts_on ?? "?"} \u2192 ${p.ends_on ?? "?"}` : "";
+    return textResult(
+      `**${p.name}** (${p.code || "no code"})
+Client: ${p.client.name}
+Active: ${p.is_active} | Billable: ${p.is_billable}
+Budget: ${p.budget ?? "none"} (${p.budget_by})
+Hourly rate: ${p.hourly_rate ?? "none"}${dates}${notes}
+ID: ${p.id}`
+    );
+  }
+);
+server.tool(
+  "list-tasks",
+  "List all tasks in the Harvest account.",
+  {
+    isActive: z.boolean().optional().describe("Filter by active status"),
+    perPage: z.number().min(1).max(2e3).default(100).describe("Results per page")
+  },
+  async (params) => {
+    const qp = {};
+    if (params.isActive !== void 0) qp["is_active"] = String(params.isActive);
+    qp["per_page"] = String(params.perPage);
+    const resp = await harvestFetch("/tasks", { params: qp });
+    const data = await assertOk(resp, "List tasks");
+    if (data.tasks.length === 0) return textResult("No tasks found.");
+    const lines = data.tasks.map((t) => {
+      const active = t.is_active ? "" : " [INACTIVE]";
+      const billable = t.billable_by_default ? "billable" : "non-billable";
+      return `- **${t.name}** \u2014 ${billable}, ${t.default_hourly_rate}/h${active} (id: ${t.id})`;
+    });
+    lines.push(`
+_Total: ${data.total_entries} tasks_`);
+    return textResult(lines.join("\n"));
+  }
+);
+server.tool(
+  "list-project-task-assignments",
+  "List task assignments for a project (which tasks can be logged against a project).",
+  {
+    projectId: z.number().describe("Project ID"),
+    isActive: z.boolean().optional().describe("Filter by active status")
+  },
+  async (params) => {
+    const qp = {};
+    if (params.isActive !== void 0) qp["is_active"] = String(params.isActive);
+    const resp = await harvestFetch(
+      `/projects/${params.projectId}/task_assignments`,
+      { params: qp }
+    );
+    const data = await assertOk(resp, "List task assignments");
+    if (data.task_assignments.length === 0) return textResult("No task assignments found.");
+    const lines = data.task_assignments.map((ta) => {
+      const billable = ta.billable ? "billable" : "non-billable";
+      const rate = ta.hourly_rate ? `, ${ta.hourly_rate}/h` : "";
+      const budget = ta.budget ? `, budget: ${ta.budget}h` : "";
+      return `- **${ta.task.name}** \u2014 ${billable}${rate}${budget} (task_id: ${ta.task.id})`;
+    });
+    lines.push(`
+_Total: ${data.total_entries} assignments_`);
+    return textResult(lines.join("\n"));
+  }
+);
+server.tool(
+  "get-me",
+  "Get the currently authenticated user profile.",
+  {},
+  async () => {
+    const resp = await harvestFetch("/users/me");
+    const u = await assertOk(resp, "Get me");
+    const capacity = (u.weekly_capacity / 3600).toFixed(0);
+    return textResult(
+      `**${u.first_name} ${u.last_name}**
+Email: ${u.email}
+Timezone: ${u.timezone}
+Weekly capacity: ${capacity}h
+Roles: ${u.roles.join(", ") || "none"}
+ID: ${u.id}`
+    );
+  }
+);
+server.tool(
+  "list-users",
+  "List all users in the Harvest account.",
+  {
+    isActive: z.boolean().optional().describe("Filter by active status"),
+    perPage: z.number().min(1).max(2e3).default(100).describe("Results per page")
+  },
+  async (params) => {
+    const qp = {};
+    if (params.isActive !== void 0) qp["is_active"] = String(params.isActive);
+    qp["per_page"] = String(params.perPage);
+    const resp = await harvestFetch("/users", { params: qp });
+    const data = await assertOk(resp, "List users");
+    if (data.users.length === 0) return textResult("No users found.");
+    const lines = data.users.map((u) => {
+      const active = u.is_active ? "" : " [INACTIVE]";
+      return `- **${u.first_name} ${u.last_name}** \u2014 ${u.email}${active} (id: ${u.id})`;
+    });
+    lines.push(`
+_Total: ${data.total_entries} users_`);
+    return textResult(lines.join("\n"));
+  }
+);
+server.tool(
+  "list-clients",
+  "List all clients in the Harvest account.",
+  {
+    isActive: z.boolean().optional().describe("Filter by active status"),
+    perPage: z.number().min(1).max(2e3).default(100).describe("Results per page")
+  },
+  async (params) => {
+    const qp = {};
+    if (params.isActive !== void 0) qp["is_active"] = String(params.isActive);
+    qp["per_page"] = String(params.perPage);
+    const resp = await harvestFetch("/clients", { params: qp });
+    const data = await assertOk(resp, "List clients");
+    if (data.clients.length === 0) return textResult("No clients found.");
+    const lines = data.clients.map((c) => {
+      const active = c.is_active ? "" : " [INACTIVE]";
+      return `- **${c.name}** \u2014 ${c.currency}${active} (id: ${c.id})`;
+    });
+    lines.push(`
+_Total: ${data.total_entries} clients_`);
+    return textResult(lines.join("\n"));
+  }
+);
+server.tool(
+  "create-project",
+  "Create a new project.",
+  {
+    clientId: z.number().describe("Client ID"),
+    name: z.string().describe("Project name"),
+    isBillable: z.boolean().describe("Whether the project is billable"),
+    billBy: z.enum(["Project", "Tasks", "People", "none"]).describe("Billing method"),
+    budgetBy: z.enum(["project", "project_cost", "task", "task_fees", "person", "none"]).describe("Budget method"),
+    code: z.string().optional().describe("Project code"),
+    isActive: z.boolean().optional().describe("Active status (default: true)"),
+    isFixedFee: z.boolean().optional().describe("Fixed fee project"),
+    hourlyRate: z.number().optional().describe("Hourly rate"),
+    budget: z.number().optional().describe("Budget in hours"),
+    budgetIsMonthly: z.boolean().optional().describe("Monthly budget (default: false)"),
+    costBudget: z.number().optional().describe("Monetary budget"),
+    fee: z.number().optional().describe("Fixed fee amount"),
+    notes: z.string().optional().describe("Project notes"),
+    startsOn: z.string().optional().describe("Start date (YYYY-MM-DD)"),
+    endsOn: z.string().optional().describe("End date (YYYY-MM-DD)"),
+    notifyWhenOverBudget: z.boolean().optional().describe("Notify when over budget"),
+    overBudgetNotificationPercentage: z.number().optional().describe("Budget notification threshold %"),
+    showBudgetToAll: z.boolean().optional().describe("Show budget to all users")
+  },
+  async (params) => {
+    const body = {
+      client_id: params.clientId,
+      name: params.name,
+      is_billable: params.isBillable,
+      bill_by: params.billBy,
+      budget_by: params.budgetBy
+    };
+    if (params.code) body["code"] = params.code;
+    if (params.isActive !== void 0) body["is_active"] = params.isActive;
+    if (params.isFixedFee !== void 0) body["is_fixed_fee"] = params.isFixedFee;
+    if (params.hourlyRate !== void 0) body["hourly_rate"] = params.hourlyRate;
+    if (params.budget !== void 0) body["budget"] = params.budget;
+    if (params.budgetIsMonthly !== void 0) body["budget_is_monthly"] = params.budgetIsMonthly;
+    if (params.costBudget !== void 0) body["cost_budget"] = params.costBudget;
+    if (params.fee !== void 0) body["fee"] = params.fee;
+    if (params.notes) body["notes"] = params.notes;
+    if (params.startsOn) body["starts_on"] = params.startsOn;
+    if (params.endsOn) body["ends_on"] = params.endsOn;
+    if (params.notifyWhenOverBudget !== void 0)
+      body["notify_when_over_budget"] = params.notifyWhenOverBudget;
+    if (params.overBudgetNotificationPercentage !== void 0)
+      body["over_budget_notification_percentage"] = params.overBudgetNotificationPercentage;
+    if (params.showBudgetToAll !== void 0) body["show_budget_to_all"] = params.showBudgetToAll;
+    const resp = await harvestFetch("/projects", { method: "POST", body: JSON.stringify(body) });
+    const p = await assertOk(resp, "Create project");
+    return textResult(`Project created!
+- **${p.name}** \u2014 ${p.client.name}
+- ID: ${p.id}`);
+  }
+);
+server.tool(
+  "update-project",
+  "Update an existing project.",
+  {
+    projectId: z.number().describe("Project ID"),
+    name: z.string().optional().describe("New name"),
+    clientId: z.number().optional().describe("New client ID"),
+    isBillable: z.boolean().optional().describe("Billable status"),
+    billBy: z.enum(["Project", "Tasks", "People", "none"]).optional().describe("Billing method"),
+    budgetBy: z.enum(["project", "project_cost", "task", "task_fees", "person", "none"]).optional().describe("Budget method"),
+    code: z.string().optional().describe("Project code"),
+    isActive: z.boolean().optional().describe("Active status"),
+    hourlyRate: z.number().optional().describe("Hourly rate"),
+    budget: z.number().optional().describe("Budget in hours"),
+    fee: z.number().optional().describe("Fixed fee amount"),
+    notes: z.string().optional().describe("Project notes"),
+    startsOn: z.string().optional().describe("Start date (YYYY-MM-DD)"),
+    endsOn: z.string().optional().describe("End date (YYYY-MM-DD)")
+  },
+  async (params) => {
+    const body = {};
+    if (params.name) body["name"] = params.name;
+    if (params.clientId) body["client_id"] = params.clientId;
+    if (params.isBillable !== void 0) body["is_billable"] = params.isBillable;
+    if (params.billBy) body["bill_by"] = params.billBy;
+    if (params.budgetBy) body["budget_by"] = params.budgetBy;
+    if (params.code) body["code"] = params.code;
+    if (params.isActive !== void 0) body["is_active"] = params.isActive;
+    if (params.hourlyRate !== void 0) body["hourly_rate"] = params.hourlyRate;
+    if (params.budget !== void 0) body["budget"] = params.budget;
+    if (params.fee !== void 0) body["fee"] = params.fee;
+    if (params.notes !== void 0) body["notes"] = params.notes;
+    if (params.startsOn) body["starts_on"] = params.startsOn;
+    if (params.endsOn) body["ends_on"] = params.endsOn;
+    const resp = await harvestFetch(`/projects/${params.projectId}`, { method: "PATCH", body: JSON.stringify(body) });
+    const p = await assertOk(resp, "Update project");
+    return textResult(`Project updated: **${p.name}** (id: ${p.id})`);
+  }
+);
+server.tool(
+  "delete-project",
+  "Delete a project by ID.",
+  { projectId: z.number().describe("Project ID") },
+  async ({ projectId }) => {
+    const resp = await harvestFetch(`/projects/${projectId}`, { method: "DELETE" });
+    if (!resp.ok) {
+      const b = await resp.text();
+      throw new Error(`Delete failed (${resp.status}): ${b}`);
+    }
+    return textResult(`Project ${projectId} deleted.`);
+  }
+);
+server.tool(
+  "create-task-assignment",
+  "Assign a task to a project.",
+  {
+    projectId: z.number().describe("Project ID"),
+    taskId: z.number().describe("Task ID to assign"),
+    isActive: z.boolean().optional().describe("Active status"),
+    billable: z.boolean().optional().describe("Billable"),
+    hourlyRate: z.number().optional().describe("Hourly rate"),
+    budget: z.number().optional().describe("Budget in hours")
+  },
+  async (params) => {
+    const body = { task_id: params.taskId };
+    if (params.isActive !== void 0) body["is_active"] = params.isActive;
+    if (params.billable !== void 0) body["billable"] = params.billable;
+    if (params.hourlyRate !== void 0) body["hourly_rate"] = params.hourlyRate;
+    if (params.budget !== void 0) body["budget"] = params.budget;
+    const resp = await harvestFetch(`/projects/${params.projectId}/task_assignments`, { method: "POST", body: JSON.stringify(body) });
+    const ta = await assertOk(resp, "Create task assignment");
+    return textResult(`Task assigned: **${ta.task.name}** (assignment id: ${ta.id})`);
+  }
+);
+server.tool(
+  "update-task-assignment",
+  "Update a task assignment on a project.",
+  {
+    projectId: z.number().describe("Project ID"),
+    taskAssignmentId: z.number().describe("Task assignment ID"),
+    isActive: z.boolean().optional().describe("Active status"),
+    billable: z.boolean().optional().describe("Billable"),
+    hourlyRate: z.number().optional().describe("Hourly rate"),
+    budget: z.number().optional().describe("Budget in hours")
+  },
+  async (params) => {
+    const body = {};
+    if (params.isActive !== void 0) body["is_active"] = params.isActive;
+    if (params.billable !== void 0) body["billable"] = params.billable;
+    if (params.hourlyRate !== void 0) body["hourly_rate"] = params.hourlyRate;
+    if (params.budget !== void 0) body["budget"] = params.budget;
+    const resp = await harvestFetch(`/projects/${params.projectId}/task_assignments/${params.taskAssignmentId}`, { method: "PATCH", body: JSON.stringify(body) });
+    const ta = await assertOk(resp, "Update task assignment");
+    return textResult(`Task assignment updated: **${ta.task.name}** (id: ${ta.id})`);
+  }
+);
+server.tool(
+  "delete-task-assignment",
+  "Remove a task assignment from a project.",
+  {
+    projectId: z.number().describe("Project ID"),
+    taskAssignmentId: z.number().describe("Task assignment ID")
+  },
+  async ({ projectId, taskAssignmentId }) => {
+    const resp = await harvestFetch(`/projects/${projectId}/task_assignments/${taskAssignmentId}`, { method: "DELETE" });
+    if (!resp.ok) {
+      const b = await resp.text();
+      throw new Error(`Delete failed (${resp.status}): ${b}`);
+    }
+    return textResult(`Task assignment ${taskAssignmentId} deleted.`);
+  }
+);
+server.tool(
+  "list-project-user-assignments",
+  "List user assignments for a project (which users are assigned).",
+  {
+    projectId: z.number().describe("Project ID"),
+    isActive: z.boolean().optional().describe("Filter by active status")
+  },
+  async (params) => {
+    const qp = {};
+    if (params.isActive !== void 0) qp["is_active"] = String(params.isActive);
+    const resp = await harvestFetch(`/projects/${params.projectId}/user_assignments`, { params: qp });
+    const data = await assertOk(resp, "List user assignments");
+    if (data.user_assignments.length === 0) return textResult("No user assignments found.");
+    const lines = data.user_assignments.map((ua) => {
+      const pm = ua.is_project_manager ? " [PM]" : "";
+      const rate = ua.hourly_rate ? `, ${ua.hourly_rate}/h` : "";
+      return `- **${ua.user.name}**${pm}${rate} (user_id: ${ua.user.id}, assignment_id: ${ua.id})`;
+    });
+    lines.push(`
+_Total: ${data.total_entries} assignments_`);
+    return textResult(lines.join("\n"));
+  }
+);
+server.tool(
+  "create-user-assignment",
+  "Assign a user to a project.",
+  {
+    projectId: z.number().describe("Project ID"),
+    userId: z.number().describe("User ID to assign"),
+    isActive: z.boolean().optional().describe("Active status"),
+    isProjectManager: z.boolean().optional().describe("Project manager role"),
+    useDefaultRates: z.boolean().optional().describe("Use default rates"),
+    hourlyRate: z.number().optional().describe("Hourly rate"),
+    budget: z.number().optional().describe("Budget in hours")
+  },
+  async (params) => {
+    const body = { user_id: params.userId };
+    if (params.isActive !== void 0) body["is_active"] = params.isActive;
+    if (params.isProjectManager !== void 0) body["is_project_manager"] = params.isProjectManager;
+    if (params.useDefaultRates !== void 0) body["use_default_rates"] = params.useDefaultRates;
+    if (params.hourlyRate !== void 0) body["hourly_rate"] = params.hourlyRate;
+    if (params.budget !== void 0) body["budget"] = params.budget;
+    const resp = await harvestFetch(`/projects/${params.projectId}/user_assignments`, { method: "POST", body: JSON.stringify(body) });
+    const ua = await assertOk(resp, "Create user assignment");
+    return textResult(`User assigned: **${ua.user.name}** (assignment id: ${ua.id})`);
+  }
+);
+server.tool(
+  "update-user-assignment",
+  "Update a user assignment on a project.",
+  {
+    projectId: z.number().describe("Project ID"),
+    userAssignmentId: z.number().describe("User assignment ID"),
+    isActive: z.boolean().optional().describe("Active status"),
+    isProjectManager: z.boolean().optional().describe("Project manager role"),
+    useDefaultRates: z.boolean().optional().describe("Use default rates"),
+    hourlyRate: z.number().optional().describe("Hourly rate"),
+    budget: z.number().optional().describe("Budget in hours")
+  },
+  async (params) => {
+    const body = {};
+    if (params.isActive !== void 0) body["is_active"] = params.isActive;
+    if (params.isProjectManager !== void 0) body["is_project_manager"] = params.isProjectManager;
+    if (params.useDefaultRates !== void 0) body["use_default_rates"] = params.useDefaultRates;
+    if (params.hourlyRate !== void 0) body["hourly_rate"] = params.hourlyRate;
+    if (params.budget !== void 0) body["budget"] = params.budget;
+    const resp = await harvestFetch(`/projects/${params.projectId}/user_assignments/${params.userAssignmentId}`, { method: "PATCH", body: JSON.stringify(body) });
+    const ua = await assertOk(resp, "Update user assignment");
+    return textResult(`User assignment updated: **${ua.user.name}** (id: ${ua.id})`);
+  }
+);
+server.tool(
+  "delete-user-assignment",
+  "Remove a user assignment from a project.",
+  {
+    projectId: z.number().describe("Project ID"),
+    userAssignmentId: z.number().describe("User assignment ID")
+  },
+  async ({ projectId, userAssignmentId }) => {
+    const resp = await harvestFetch(`/projects/${projectId}/user_assignments/${userAssignmentId}`, { method: "DELETE" });
+    if (!resp.ok) {
+      const b = await resp.text();
+      throw new Error(`Delete failed (${resp.status}): ${b}`);
+    }
+    return textResult(`User assignment ${userAssignmentId} deleted.`);
+  }
+);
+server.tool(
+  "create-task",
+  "Create a new task in the Harvest account.",
+  {
+    name: z.string().describe("Task name"),
+    billableByDefault: z.boolean().optional().describe("Billable by default (default: true)"),
+    defaultHourlyRate: z.number().optional().describe("Default hourly rate"),
+    isDefault: z.boolean().optional().describe("Auto-add to new projects"),
+    isActive: z.boolean().optional().describe("Active status")
+  },
+  async (params) => {
+    const body = { name: params.name };
+    if (params.billableByDefault !== void 0) body["billable_by_default"] = params.billableByDefault;
+    if (params.defaultHourlyRate !== void 0) body["default_hourly_rate"] = params.defaultHourlyRate;
+    if (params.isDefault !== void 0) body["is_default"] = params.isDefault;
+    if (params.isActive !== void 0) body["is_active"] = params.isActive;
+    const resp = await harvestFetch("/tasks", { method: "POST", body: JSON.stringify(body) });
+    const t = await assertOk(resp, "Create task");
+    return textResult(`Task created: **${t.name}** (id: ${t.id})`);
+  }
+);
+server.tool(
+  "update-task",
+  "Update an existing task.",
+  {
+    taskId: z.number().describe("Task ID"),
+    name: z.string().optional().describe("New name"),
+    billableByDefault: z.boolean().optional().describe("Billable by default"),
+    defaultHourlyRate: z.number().optional().describe("Default hourly rate"),
+    isDefault: z.boolean().optional().describe("Auto-add to new projects"),
+    isActive: z.boolean().optional().describe("Active status")
+  },
+  async (params) => {
+    const body = {};
+    if (params.name) body["name"] = params.name;
+    if (params.billableByDefault !== void 0) body["billable_by_default"] = params.billableByDefault;
+    if (params.defaultHourlyRate !== void 0) body["default_hourly_rate"] = params.defaultHourlyRate;
+    if (params.isDefault !== void 0) body["is_default"] = params.isDefault;
+    if (params.isActive !== void 0) body["is_active"] = params.isActive;
+    const resp = await harvestFetch(`/tasks/${params.taskId}`, { method: "PATCH", body: JSON.stringify(body) });
+    const t = await assertOk(resp, "Update task");
+    return textResult(`Task updated: **${t.name}** (id: ${t.id})`);
+  }
+);
+server.tool(
+  "delete-task",
+  "Delete a task by ID.",
+  { taskId: z.number().describe("Task ID") },
+  async ({ taskId }) => {
+    const resp = await harvestFetch(`/tasks/${taskId}`, { method: "DELETE" });
+    if (!resp.ok) {
+      const b = await resp.text();
+      throw new Error(`Delete failed (${resp.status}): ${b}`);
+    }
+    return textResult(`Task ${taskId} deleted.`);
+  }
+);
+server.tool(
+  "get-client",
+  "Retrieve a single client by ID.",
+  { clientId: z.number().describe("Client ID") },
+  async ({ clientId }) => {
+    const resp = await harvestFetch(`/clients/${clientId}`);
+    const c = await assertOk(resp, "Get client");
+    const address = c.address ? `
+Address: ${c.address}` : "";
+    return textResult(`**${c.name}**
+Currency: ${c.currency}
+Active: ${c.is_active}${address}
+ID: ${c.id}`);
+  }
+);
+server.tool(
+  "create-client",
+  "Create a new client.",
+  {
+    name: z.string().describe("Client name"),
+    isActive: z.boolean().optional().describe("Active status"),
+    address: z.string().optional().describe("Client address"),
+    currency: z.string().optional().describe("Currency code (e.g. EUR, USD)")
+  },
+  async (params) => {
+    const body = { name: params.name };
+    if (params.isActive !== void 0) body["is_active"] = params.isActive;
+    if (params.address) body["address"] = params.address;
+    if (params.currency) body["currency"] = params.currency;
+    const resp = await harvestFetch("/clients", { method: "POST", body: JSON.stringify(body) });
+    const c = await assertOk(resp, "Create client");
+    return textResult(`Client created: **${c.name}** (id: ${c.id})`);
+  }
+);
+server.tool(
+  "update-client",
+  "Update an existing client.",
+  {
+    clientId: z.number().describe("Client ID"),
+    name: z.string().optional().describe("New name"),
+    isActive: z.boolean().optional().describe("Active status"),
+    address: z.string().optional().describe("Address"),
+    currency: z.string().optional().describe("Currency code")
+  },
+  async (params) => {
+    const body = {};
+    if (params.name) body["name"] = params.name;
+    if (params.isActive !== void 0) body["is_active"] = params.isActive;
+    if (params.address !== void 0) body["address"] = params.address;
+    if (params.currency) body["currency"] = params.currency;
+    const resp = await harvestFetch(`/clients/${params.clientId}`, { method: "PATCH", body: JSON.stringify(body) });
+    const c = await assertOk(resp, "Update client");
+    return textResult(`Client updated: **${c.name}** (id: ${c.id})`);
+  }
+);
+server.tool(
+  "delete-client",
+  "Delete a client by ID.",
+  { clientId: z.number().describe("Client ID") },
+  async ({ clientId }) => {
+    const resp = await harvestFetch(`/clients/${clientId}`, { method: "DELETE" });
+    if (!resp.ok) {
+      const b = await resp.text();
+      throw new Error(`Delete failed (${resp.status}): ${b}`);
+    }
+    return textResult(`Client ${clientId} deleted.`);
+  }
+);
+server.tool(
+  "get-user",
+  "Retrieve a single user by ID.",
+  { userId: z.number().describe("User ID") },
+  async ({ userId }) => {
+    const resp = await harvestFetch(`/users/${userId}`);
+    const u = await assertOk(resp, "Get user");
+    const capacity = (u.weekly_capacity / 3600).toFixed(0);
+    return textResult(
+      `**${u.first_name} ${u.last_name}**
+Email: ${u.email}
+Timezone: ${u.timezone}
+Capacity: ${capacity}h/week
+Contractor: ${u.is_contractor}
+Roles: ${u.roles.join(", ") || "none"}
+Access: ${u.access_roles.join(", ") || "member"}
+Active: ${u.is_active}
+ID: ${u.id}`
+    );
+  }
+);
+server.tool(
+  "create-user",
+  "Create a new user in the Harvest account.",
+  {
+    firstName: z.string().describe("First name"),
+    lastName: z.string().describe("Last name"),
+    email: z.string().describe("Email address"),
+    timezone: z.string().optional().describe("Timezone"),
+    isContractor: z.boolean().optional().describe("Contractor status"),
+    isActive: z.boolean().optional().describe("Active status"),
+    weeklyCapacity: z.number().optional().describe("Weekly capacity in seconds"),
+    defaultHourlyRate: z.number().optional().describe("Default hourly rate"),
+    costRate: z.number().optional().describe("Cost rate"),
+    roles: z.array(z.string()).optional().describe("Roles"),
+    accessRoles: z.array(z.string()).optional().describe("Access roles (administrator, manager, member)"),
+    hasAccessToAllFutureProjects: z.boolean().optional().describe("Access to all future projects")
+  },
+  async (params) => {
+    const body = {
+      first_name: params.firstName,
+      last_name: params.lastName,
+      email: params.email
+    };
+    if (params.timezone) body["timezone"] = params.timezone;
+    if (params.isContractor !== void 0) body["is_contractor"] = params.isContractor;
+    if (params.isActive !== void 0) body["is_active"] = params.isActive;
+    if (params.weeklyCapacity !== void 0) body["weekly_capacity"] = params.weeklyCapacity;
+    if (params.defaultHourlyRate !== void 0) body["default_hourly_rate"] = params.defaultHourlyRate;
+    if (params.costRate !== void 0) body["cost_rate"] = params.costRate;
+    if (params.roles) body["roles"] = params.roles;
+    if (params.accessRoles) body["access_roles"] = params.accessRoles;
+    if (params.hasAccessToAllFutureProjects !== void 0)
+      body["has_access_to_all_future_projects"] = params.hasAccessToAllFutureProjects;
+    const resp = await harvestFetch("/users", { method: "POST", body: JSON.stringify(body) });
+    const u = await assertOk(resp, "Create user");
+    return textResult(`User created: **${u.first_name} ${u.last_name}** (id: ${u.id})`);
+  }
+);
+server.tool(
+  "update-user",
+  "Update an existing user.",
+  {
+    userId: z.number().describe("User ID"),
+    firstName: z.string().optional().describe("First name"),
+    lastName: z.string().optional().describe("Last name"),
+    email: z.string().optional().describe("Email address"),
+    timezone: z.string().optional().describe("Timezone"),
+    isContractor: z.boolean().optional().describe("Contractor status"),
+    isActive: z.boolean().optional().describe("Active status (false to archive)"),
+    weeklyCapacity: z.number().optional().describe("Weekly capacity in seconds"),
+    roles: z.array(z.string()).optional().describe("Roles"),
+    accessRoles: z.array(z.string()).optional().describe("Access roles")
+  },
+  async (params) => {
+    const body = {};
+    if (params.firstName) body["first_name"] = params.firstName;
+    if (params.lastName) body["last_name"] = params.lastName;
+    if (params.email) body["email"] = params.email;
+    if (params.timezone) body["timezone"] = params.timezone;
+    if (params.isContractor !== void 0) body["is_contractor"] = params.isContractor;
+    if (params.isActive !== void 0) body["is_active"] = params.isActive;
+    if (params.weeklyCapacity !== void 0) body["weekly_capacity"] = params.weeklyCapacity;
+    if (params.roles) body["roles"] = params.roles;
+    if (params.accessRoles) body["access_roles"] = params.accessRoles;
+    const resp = await harvestFetch(`/users/${params.userId}`, { method: "PATCH", body: JSON.stringify(body) });
+    const u = await assertOk(resp, "Update user");
+    return textResult(`User updated: **${u.first_name} ${u.last_name}** (id: ${u.id})`);
+  }
+);
+server.tool(
+  "delete-user",
+  "Delete a user by ID (only if no time entries or expenses).",
+  { userId: z.number().describe("User ID") },
+  async ({ userId }) => {
+    const resp = await harvestFetch(`/users/${userId}`, { method: "DELETE" });
+    if (!resp.ok) {
+      const b = await resp.text();
+      throw new Error(`Delete failed (${resp.status}): ${b}`);
+    }
+    return textResult(`User ${userId} deleted.`);
+  }
+);
+server.tool(
+  "get-company",
+  "Get company information and settings.",
+  {},
+  async () => {
+    const resp = await harvestFetch("/company");
+    const c = await assertOk(resp, "Get company");
+    const capacity = (c.weekly_capacity / 3600).toFixed(0);
+    return textResult(
+      `**${c.name}**
+Domain: ${c.full_domain}
+Plan: ${c.plan_type}
+Week starts: ${c.week_start_day}
+Time format: ${c.time_format} (${c.clock})
+Currency: ${c.currency_code_display}
+Weekly capacity: ${capacity}h`
+    );
+  }
+);
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+main().catch((err) => {
+  process.stderr.write(`Fatal: ${err instanceof Error ? err.message : String(err)}
+`);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@mnicole-dev/harvest-mcp-server",
+  "version": "1.0.0",
+  "description": "MCP server for the Harvest time tracking API (v2)",
+  "type": "module",
+  "bin": {
+    "harvest-mcp-server": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --out-dir dist --clean",
+    "dev": "tsx src/index.ts"
+  },
+  "keywords": [
+    "mcp",
+    "harvest",
+    "time-tracking",
+    "timesheet",
+    "model-context-protocol"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "tsup": "^8.4.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.8.0"
+  }
+}