Harvest MCP

1. Install the SDK

   Node.js

   npm install @scalekit-sdk/node

   Python

   pip install scalekit

   Full SDK reference: Node.js | Python

2. Set your credentials

   Add your Scalekit credentials to your .env file. Find values in app.scalekit.com > Developers > API Credentials.

   .env

   SCALEKIT_ENVIRONMENT_URL=<your-environment-url>
   SCALEKIT_CLIENT_ID=<your-client-id>
   SCALEKIT_CLIENT_SECRET=<your-client-secret>

3. Authorize and make your first call

   Node.js

   quickstart.ts

   import { ScalekitClient } from '@scalekit-sdk/node'
   import 'dotenv/config'
   
   const scalekit = new ScalekitClient(
     process.env.SCALEKIT_ENV_URL,
     process.env.SCALEKIT_CLIENT_ID,
     process.env.SCALEKIT_CLIENT_SECRET,
   )
   const actions = scalekit.actions
   
   const connector = 'harvestmcp'
   const identifier = 'user_123'
   
   // Generate an authorization link for the user
   const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })
   console.log('Authorize Harvest MCP:', link)
   process.stdout.write('Press Enter after authorizing...')
   await new Promise(r => process.stdin.once('data', r))
   
   // Make your first call
   const result = await actions.executeTool({
     connector,
     identifier,
     toolName: 'harvestmcp_get_account_settings',
     toolInput: {},
   })
   console.log(result)

   Python

   quickstart.py

   import os
   from scalekit.client import ScalekitClient
   from dotenv import load_dotenv
   load_dotenv()
   
   scalekit_client = ScalekitClient(
       env_url=os.getenv("SCALEKIT_ENV_URL"),
       client_id=os.getenv("SCALEKIT_CLIENT_ID"),
       client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"),
   )
   actions = scalekit_client.actions
   
   connection_name = "harvestmcp"
   identifier = "user_123"
   
   # Generate an authorization link for the user
   link_response = actions.get_authorization_link(
       connection_name=connection_name,
       identifier=identifier,
   )
   print("Authorize Harvest MCP:", link_response.link)
   input("Press Enter after authorizing...")
   
   # Make your first call
   result = actions.execute_tool(
       tool_input={},
       tool_name="harvestmcp_get_account_settings",
       connection_name=connection_name,
       identifier=identifier,
   )
   print(result)

What you can do

Connect this agent connector to let your agent:

• Update time entry, task, project — Update an existing time entry
• Project unassign user from, remove task from, assign user to — Remove a user from a project
• Timesheet submit — Submit a timesheet period for approval
• Feedback submit — Submit feedback or a support message to Harvest
• Timer stop, start — Stop the currently running timer for the authenticated user
• Time log — Log a completed time entry

Tool list

Use the exact tool names from the Tool list below when you call execute_tool. If you’re not sure which name to use, list the tools available for the current user first.

harvestmcp_add_task_to_project#Add an existing task to a project. project_id and task_id are required.2 params▾

Add an existing task to a project. project_id and task_id are required.

NameTypeRequiredDescription

project_idintegerrequiredProject id to add the task to.

task_idintegerrequiredTask id to add.

harvestmcp_assign_user_to_project#Assign a user to a project. project_id and user_id are required.2 params▾

Assign a user to a project. project_id and user_id are required.

NameTypeRequiredDescription

project_idintegerrequiredProject id to assign the user to.

user_idintegerrequiredUser id to assign.

harvestmcp_create_client#Create a new client. name is required.3 params▾

Create a new client. name is required.

NameTypeRequiredDescription

namestringrequiredClient name.

addressstringoptionalClient mailing address.

currency_codestringoptionalISO 4217 currency code (e.g. USD).

harvestmcp_create_expense#Log a new expense. project_id and expense_category_id are required. Provide total_cost for amount-based categories, or units for unit-based categories.8 params▾

Log a new expense. project_id and expense_category_id are required. Provide total_cost for amount-based categories, or units for unit-based categories.

NameTypeRequiredDescription

expense_category_idintegerrequiredExpense category id.

project_idintegerrequiredProject id to log the expense against.

billablebooleanoptionalWhether the expense is billable to the client. Defaults to true.

notesstringoptionalOptional description of the expense.

spent_atstringoptionalDate the expense was incurred (YYYY-MM-DD). Defaults to today in the user's timezone.

total_costnumberoptionalTotal cost of the expense. Use for amount-based categories.

unitsnumberoptionalNumber of units. Use for unit-based categories; cost is computed from the category's unit price.

user_idintegeroptionalCreate on behalf of another user. Requires manager/admin permissions; defaults to the authenticated user.

harvestmcp_create_invoice#Create a free-form draft invoice for a client. client_id is required; supply line_items for the invoice content. Invoice number is assigned automatically; invoice is created as draft.13 params▾

Create a free-form draft invoice for a client. client_id is required; supply line_items for the invoice content. Invoice number is assigned automatically; invoice is created as draft.

NameTypeRequiredDescription

client_idintegerrequiredClient id the invoice is for.

currencystringoptionalISO 4217 currency code (e.g. USD, EUR).

discountnumberoptionalOptional discount as a percentage.

due_datestringoptionalDue date (YYYY-MM-DD).

issue_datestringoptionalIssue date (YYYY-MM-DD). Defaults to today.

line_itemsarrayoptionalInvoice line items. Each item: {kind, description, quantity, unit_price, taxed, taxed2, project_id}.

notesstringoptionalOptional notes shown on the invoice.

payment_optionsarrayoptionalOnline payment methods to accept. Defaults to the company's default accepted methods.

payment_termstringoptionalPayment term (e.g. "net 30", "upon receipt"); ignored when due_date is given.

purchase_orderstringoptionalOptional purchase order reference.

subjectstringoptionalOptional invoice subject line.

taxnumberoptionalOptional first tax rate as a percentage.

tax2numberoptionalOptional second tax rate as a percentage.

harvestmcp_create_invoice_from_tracked_time#Create a draft invoice for a client by importing uninvoiced billable tracked time and/or expenses. client_id and project_ids are required, plus at least one of `time` or `expenses`.15 params▾

Create a draft invoice for a client by importing uninvoiced billable tracked time and/or expenses. client_id and project_ids are required, plus at least one of `time` or `expenses`.

NameTypeRequiredDescription

client_idintegerrequiredClient id the invoice is for.

project_idsarrayrequiredBillable project ids to import activity from.

currencystringoptionalISO 4217 currency code.

discountnumberoptionalOptional discount as a percentage.

due_datestringoptionalDue date (YYYY-MM-DD).

expensesobjectoptionalImport expenses. Properties: summary_type (required, enum: project/people/category/detailed), from (YYYY-MM-DD), to (YYYY-MM-DD), attach_receipts (boolean).

issue_datestringoptionalIssue date (YYYY-MM-DD).

notesstringoptionalOptional notes shown on the invoice.

payment_optionsarrayoptionalOnline payment methods to accept. Defaults to the company's default accepted methods.

payment_termstringoptionalPayment term (e.g. "net 30", "upon receipt"); ignored when due_date is given.

purchase_orderstringoptionalOptional purchase order reference.

subjectstringoptionalOptional invoice subject.

taxnumberoptionalOptional first tax rate as a percentage.

tax2numberoptionalOptional second tax rate as a percentage.

timeobjectoptionalImport tracked time. Properties: summary_type (required, enum: detailed/project/task/people), from (YYYY-MM-DD), to (YYYY-MM-DD).

harvestmcp_create_project#Create a new project. client_id and name are required.6 params▾

Create a new project. client_id and name are required.

NameTypeRequiredDescription

client_idintegerrequiredClient id the project belongs to.

namestringrequiredProject name.

codestringoptionalOptional project code or short identifier.

hourly_ratenumberoptionalDefault hourly rate. Requires billable-rate permission; ignored otherwise.

is_billablebooleanoptionalWhether the project is billable. Defaults to the account's project defaults.

is_fixed_feebooleanoptionalWhether the project bills a fixed fee.

harvestmcp_create_task#Create a new task in the account. name is required.5 params▾

Create a new task in the account. name is required.

NameTypeRequiredDescription

namestringrequiredTask name.

add_to_all_projectsbooleanoptionalAlso assign this task to every active project. Runs asynchronously.

billable_by_defaultbooleanoptionalWhether the task is billable when added to a project. Defaults to true.

default_hourly_ratenumberoptionalDefault hourly rate for this task.

is_defaultbooleanoptionalIf true, this task is automatically added to new projects.

harvestmcp_delete_time_entry#Permanently delete a time entry. id is required. This cannot be undone.1 param▾

Permanently delete a time entry. id is required. This cannot be undone.

NameTypeRequiredDescription

idintegerrequiredTime entry id to delete.

harvestmcp_get_account_settings#Return account-level settings: company name, plan, timezone, week start day, hour rounding configuration, and other preferences.0 params▾

Return account-level settings: company name, plan, timezone, week start day, hour rounding configuration, and other preferences.

harvestmcp_get_expense#Return a single expense by id, including category, project, and receipt info.1 param▾

Return a single expense by id, including category, project, and receipt info.

NameTypeRequiredDescription

idintegerrequiredExpense id.

harvestmcp_get_invoice#Return a single invoice with its header and full line_items. Use list_invoices first to find the id.1 param▾

Return a single invoice with its header and full line_items. Use list_invoices first to find the id.

NameTypeRequiredDescription

idintegerrequiredInvoice id.

harvestmcp_get_project_budget#Return the budget status for a project: total budget, hours/amount spent, and remaining. project_id is required.1 param▾

Return the budget status for a project: total budget, hours/amount spent, and remaining. project_id is required.

NameTypeRequiredDescription

project_idintegerrequiredProject id to get budget for.

harvestmcp_get_running_timer#Return the currently running timer for the authenticated user, or null if no timer is running.1 param▾

Return the currently running timer for the authenticated user, or null if no timer is running.

NameTypeRequiredDescription

user_idintegeroptionalPositive integer id of a user whose running timer to check. Requires manager/admin permission for that user; defaults to the authenticated user.

harvestmcp_get_time_report#Aggregate time entries over a date range, grouped by project, client, or user. Returns billable/non-billable hours, invoiced/uninvoiced hours per group. from and to are required.4 params▾

Aggregate time entries over a date range, grouped by project, client, or user. Returns billable/non-billable hours, invoiced/uninvoiced hours per group. from and to are required.

NameTypeRequiredDescription

fromstringrequiredInclusive start date (YYYY-MM-DD, e.g. 2026-06-01).

tostringrequiredInclusive end date (YYYY-MM-DD, e.g. 2026-06-30).

group_bystringoptionalGrouping dimension. Defaults to project.

include_zero_hour_usersbooleanoptionalOnly with group_by=user. When true, also returns zero-hour rows for visible team members who logged nothing.

harvestmcp_list_clients#List clients in the user's Harvest account, ordered by name. Returns up to 100 clients per page; `total_count` is how many clients match the filter in full, so when `truncated` is true you can tell how many are missing — refine `search` or `is_active` to narrow the result.2 params▾

List clients in the user's Harvest account, ordered by name. Returns up to 100 clients per page; `total_count` is how many clients match the filter in full, so when `truncated` is true you can tell how many are missing — refine `search` or `is_active` to narrow the result.

NameTypeRequiredDescription

is_activebooleanoptionalFilter to active (true) or archived (false) clients. Omit for all.

searchstringoptionalCase-insensitive prefix match on client name.

harvestmcp_list_expense_categories#List expense categories in the account, ordered by name. Used to look up expense_category_id before creating an expense.1 param▾

List expense categories in the account, ordered by name. Used to look up expense_category_id before creating an expense.

NameTypeRequiredDescription

is_activebooleanoptionalFilter to active (true) or archived (false) categories. Omit for active categories only — pass false explicitly to see archived ones.

harvestmcp_list_expenses#List expenses, most recent first. Filter by project_id, user_id, date range, or billable status.7 params▾

List expenses, most recent first. Filter by project_id, user_id, date range, or billable status.

NameTypeRequiredDescription

billablebooleanoptionalFilter by billable status.

cursorstringoptionalOpaque pagination token from prior response's next_cursor. Omit on first request.

fromstringoptionalInclusive start date (YYYY-MM-DD).

limitintegeroptionalPage size, whole number 1–500. Omit to use the default of 100.

project_idintegeroptionalFilter to expenses for this project.

tostringoptionalInclusive end date (YYYY-MM-DD).

user_idintegeroptionalFilter to expenses for this user id. Omit to include everyone you're allowed to see.

harvestmcp_list_invoices#List invoices, most recent first. Filter by status (draft/open/sent/paid/late), client_id, issue-date range, due_date, or search term. Paginate via cursor.8 params▾

List invoices, most recent first. Filter by status (draft/open/sent/paid/late), client_id, issue-date range, due_date, or search term. Paginate via cursor.

NameTypeRequiredDescription

client_idintegeroptionalFilter to invoices for this client id.

cursorstringoptionalOpaque pagination token from prior response's next_cursor.

due_datestringoptionalFilter to invoices due on this exact date (YYYY-MM-DD).

issued_fromstringoptionalEarliest issue date, inclusive (YYYY-MM-DD).

issued_tostringoptionalLatest issue date, inclusive (YYYY-MM-DD).

limitintegeroptionalPage size, 1–500. Default 100.

searchstringoptionalCase-insensitive match on invoice number, subject, or PO number.

statusstringoptionalFilter to a single invoice status.

harvestmcp_list_project_assignments#List users assigned to a project, with their roles and billing rates. project_id is required.4 params▾

List users assigned to a project, with their roles and billing rates. project_id is required.

NameTypeRequiredDescription

project_idintegerrequiredProject id to list assignments for.

assignment_typestringoptionalWhich roster to return: users (default) or tasks.

cursorstringoptionalOpaque pagination token from prior response's next_cursor. Omit on first request.

limitintegeroptionalPage size, whole number 1–500. Omit to use the default of 100.

harvestmcp_list_projects#List projects in the user's Harvest account, ordered by client name then project name. Returns up to 100 projects per page; refine `search`, `client_ids`, or `is_active` to narrow the result.3 params▾

List projects in the user's Harvest account, ordered by client name then project name. Returns up to 100 projects per page; refine `search`, `client_ids`, or `is_active` to narrow the result.

NameTypeRequiredDescription

client_idsarrayoptionalFilter to projects belonging to any of these client ids.

is_activebooleanoptionalFilter to active (true) or archived (false) projects. Omit for all.

searchstringoptionalCase-insensitive substring match on project name or code.

harvestmcp_list_tasks#List tasks in the user's Harvest account, ordered by name. Returns up to 100 tasks per page; refine `search` or `is_active` to narrow the result.2 params▾

List tasks in the user's Harvest account, ordered by name. Returns up to 100 tasks per page; refine `search` or `is_active` to narrow the result.

NameTypeRequiredDescription

is_activebooleanoptionalFilter to active (true) or deactivated (false) tasks. Omit for active tasks only — pass false explicitly to see deactivated ones.

searchstringoptionalCase-insensitive prefix match on task name.

harvestmcp_list_time_entries#List time entries, most recent first. Defaults to the last 30 days when `from`/`to` are omitted. `hours` is the raw tracked duration. `billable` = can be billed; `is_invoiced` = has been invoiced. Paginate via `cursor`/`next_cursor`.9 params▾

List time entries, most recent first. Defaults to the last 30 days when `from`/`to` are omitted. `hours` is the raw tracked duration. `billable` = can be billed; `is_invoiced` = has been invoiced. Paginate via `cursor`/`next_cursor`.

NameTypeRequiredDescription

cursorstringoptionalOpaque pagination token from prior response's next_cursor. Omit on first request.

fromstringoptionalInclusive start date (YYYY-MM-DD, e.g. 2026-06-01).

is_invoicedbooleanoptionalFilter by invoiced status. true=invoiced only, false=uninvoiced only. Omit for both.

limitintegeroptionalPage size, 1–500. Default 100.

project_idintegeroptionalDeprecated single-id alias of project_ids; prefer project_ids. Folded into project_ids when both are given.

project_idsarrayoptionalPositive integer project ids to filter to. Omit to include all projects.

tostringoptionalInclusive end date (YYYY-MM-DD, e.g. 2026-06-01).

user_idintegeroptionalDeprecated single-id alias of user_ids; prefer user_ids. Folded into user_ids when both are given.

user_idsarrayoptionalPositive integer user ids to filter to. Omit to include everyone you're allowed to see.

harvestmcp_list_users#List team members in the user's Harvest account, ordered by id. Returns up to 100 users per page; refine `search` or `is_active` to narrow the result. Field availability follows the caller's role.2 params▾

List team members in the user's Harvest account, ordered by id. Returns up to 100 users per page; refine `search` or `is_active` to narrow the result. Field availability follows the caller's role.

NameTypeRequiredDescription

is_activebooleanoptionalFilter to active (true) or deactivated (false) users. Omit for all.

searchstringoptionalCase-insensitive prefix match on user name or email.

harvestmcp_log_time#Log a completed time entry. project_id and task_id are required, plus either hours or a started_time/ended_time pair.8 params▾

Log a completed time entry. project_id and task_id are required, plus either hours or a started_time/ended_time pair.

NameTypeRequiredDescription

project_idintegerrequiredProject id to track time against.

task_idintegerrequiredTask id within the project.

ended_timestringoptionalClock-out time in the same format as started_time. Required alongside started_time.

hoursnumberoptionalHours worked as a decimal. Provide this OR started_time + ended_time, not both.

notesstringoptionalOptional notes describing the work.

spent_atstringoptionalDate the work was performed (YYYY-MM-DD). Defaults to today in the user's timezone.

started_timestringoptionalClock-in time, e.g. "9:00am" or "14:30". Provide together with ended_time instead of hours.

user_idintegeroptionalLog on behalf of another user. Requires manager/admin permission for that user; defaults to the authenticated user.

harvestmcp_remove_task_from_project#Remove a task from a project. project_id and task_id are required.2 params▾

Remove a task from a project. project_id and task_id are required.

NameTypeRequiredDescription

project_idintegerrequiredProject id to remove the task from.

task_idintegerrequiredTask id to remove.

harvestmcp_start_timer#Start a running timer for the authenticated user on a project+task. project_id and task_id are required. At most one timer can run at a time; starting a new one stops the previous.4 params▾

Start a running timer for the authenticated user on a project+task. project_id and task_id are required. At most one timer can run at a time; starting a new one stops the previous.

NameTypeRequiredDescription

project_idintegerrequiredProject id to track time against.

task_idintegerrequiredTask id within the project.

notesstringoptionalOptional notes for the time entry.

user_idintegeroptionalStart the timer on behalf of another user. Requires manager/admin permission for that user; defaults to the authenticated user.

harvestmcp_stop_timer#Stop the currently running timer for the authenticated user. Returns the stopped time entry. No-ops if no timer is running.1 param▾

Stop the currently running timer for the authenticated user. Returns the stopped time entry. No-ops if no timer is running.

NameTypeRequiredDescription

time_entry_idintegeroptionalSpecific time entry to stop. Optional.

harvestmcp_submit_feedback#Submit feedback or a support message to Harvest. feedback is required.1 param▾

Submit feedback or a support message to Harvest. feedback is required.

NameTypeRequiredDescription

feedbackstringrequiredThe feedback message, in the user's own words. Up to 2000 characters.

harvestmcp_submit_timesheet#Submit a timesheet period for approval. period_start and period_end are required (YYYY-MM-DD).3 params▾

Submit a timesheet period for approval. period_start and period_end are required (YYYY-MM-DD).

NameTypeRequiredDescription

period_endstringrequiredLast day of the range to submit (YYYY-MM-DD).

period_startstringrequiredFirst day of the range to submit (YYYY-MM-DD).

user_idintegeroptionalSubmit on behalf of another user. Requires manager/admin permissions; defaults to the authenticated user.

harvestmcp_unassign_user_from_project#Remove a user from a project. project_id and user_id are required.2 params▾

Remove a user from a project. project_id and user_id are required.

NameTypeRequiredDescription

project_idintegerrequiredProject id to remove the user from.

user_idintegerrequiredUser id to remove.

harvestmcp_update_client#Update an existing client. id is required. Only provided fields are changed.5 params▾

Update an existing client. id is required. Only provided fields are changed.

NameTypeRequiredDescription

idintegerrequiredClient id to update.

addressstringoptionalNew mailing address.

currency_codestringoptionalNew ISO 4217 currency code.

is_activebooleanoptionalSet to false to archive the client.

namestringoptionalNew client name.

harvestmcp_update_expense#Update an existing expense. id is required. Only provided fields are changed.9 params▾

Update an existing expense. id is required. Only provided fields are changed.

NameTypeRequiredDescription

idintegerrequiredExpense id to update.

billablebooleanoptionalWhether the expense is billable.

delete_receiptbooleanoptionalRemove the attached receipt.

expense_category_idintegeroptionalNew expense category id.

notesstringoptionalNew notes.

project_idintegeroptionalNew project id.

spent_atstringoptionalNew date (YYYY-MM-DD).

total_costnumberoptionalNew total cost.

unitsnumberoptionalNew number of units.

harvestmcp_update_project#Update an existing project. id is required. Only provided fields are changed.7 params▾

Update an existing project. id is required. Only provided fields are changed.

NameTypeRequiredDescription

idintegerrequiredProject id to update.

bill_bystringoptionalHow the project bills (Tasks, People, Project, none).

codestringoptionalNew project code.

hourly_ratenumberoptionalHourly rate when bill_by is Project. Requires billable-rate permission.

is_activebooleanoptionalSet to false to archive the project.

namestringoptionalNew project name.

project_typestringoptionalProject type.

harvestmcp_update_task#Update an existing task. id is required. Only provided fields are changed.4 params▾

Update an existing task. id is required. Only provided fields are changed.

NameTypeRequiredDescription

idintegerrequiredTask id to update.

default_hourly_ratenumberoptionalNew default hourly rate.

is_activebooleanoptionalSet to false to deactivate the task.

namestringoptionalNew task name.

harvestmcp_update_time_entry#Update an existing time entry. id is required. Only provided fields are changed.8 params▾

Update an existing time entry. id is required. Only provided fields are changed.

NameTypeRequiredDescription

idintegerrequiredTime entry id to update.

ended_timestringoptionalNew clock-out time in the same format as started_time. Required alongside started_time.

hoursnumberoptionalNew hours value. Provide this OR started_time + ended_time, not both.

notesstringoptionalNew notes.

project_idintegeroptionalNew project id.

spent_atstringoptionalNew date (YYYY-MM-DD).

started_timestringoptionalNew clock-in time, e.g. "9:00am" or "14:30". Provide together with ended_time instead of hours.

task_idintegeroptionalNew task id.