Harvest MCP connector

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:

• Project add task to, assign user to, remove task from — Add an existing task to a project
• Create client, expense, invoice — Create a new client
• Delete time entry — Permanently delete a time entry
• Get account settings, expense, invoice — Return account-level settings: company name, plan, timezone, week start day, hour rounding configuration, and other preferences
• List clients, expense categories, expenses — List clients in the user’s Harvest account, ordered by name
• Time log — Log a duration-based time entry (not a timer)

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.4 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.

billablebooleanoptionalWhether the task is billable on this project. Defaults to the task's billable_by_default.

hourly_ratenumberoptionalHourly rate for this task on this project.

harvestmcp_assign_user_to_project#Assign a user to a project. project_id and user_id are required.5 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.

budgetnumberoptionalOptional user-level budget in hours.

hourly_ratenumberoptionalHourly rate for this user on this project.

is_project_managerbooleanoptionalWhether to grant project manager role for this project.

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.

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

harvestmcp_create_expense#Log a new expense. project_id, expense_category_id, spent_date, and total_cost are required.6 params▾

Log a new expense. project_id, expense_category_id, spent_date, and total_cost are required.

NameTypeRequiredDescription

expense_category_idintegerrequiredExpense category id.

project_idintegerrequiredProject id to log the expense against.

spent_datestringrequiredDate the expense was incurred (YYYY-MM-DD).

total_costnumberrequiredTotal cost of the expense.

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

notesstringoptionalOptional description of the expense.

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.7 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).

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}.

notesstringoptionalOptional notes shown on the invoice.

subjectstringoptionalOptional invoice subject line.

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`.8 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.

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).

issue_datestringoptionalIssue date (YYYY-MM-DD).

subjectstringoptionalOptional invoice subject.

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.10 params▾

Create a new project. client_id and name are required.

NameTypeRequiredDescription

client_idintegerrequiredClient id the project belongs to.

namestringrequiredProject name.

budgetnumberoptionalOptional budget amount in hours or currency.

budget_bystringoptionalHow the budget is tracked.

codestringoptionalOptional project code or short identifier.

ends_onstringoptionalProject end date (YYYY-MM-DD).

hourly_ratenumberoptionalDefault hourly rate for the project.

is_billablebooleanoptionalWhether the project is billable. Defaults to true.

notesstringoptionalOptional project notes.

starts_onstringoptionalProject start date (YYYY-MM-DD).

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.

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

default_hourly_ratenumberoptionalDefault hourly rate for this task.

is_activebooleanoptionalWhether the task is active. Defaults to true.

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.0 params▾

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

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.0 params▾

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

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

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

NameTypeRequiredDescription

client_idintegeroptionalFilter to expenses for this client.

fromstringoptionalInclusive start date (YYYY-MM-DD).

is_billablebooleanoptionalFilter by billable status.

project_idintegeroptionalFilter to expenses for this project.

tostringoptionalInclusive end date (YYYY-MM-DD).

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.1 param▾

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

NameTypeRequiredDescription

project_idintegerrequiredProject id to list assignments for.

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`.7 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_idintegeroptionalPositive integer id of a project to filter to. Omit to include all projects.

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

user_idintegeroptionalPositive integer id of a user to filter to. Omit to default to yourself.

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 duration-based time entry (not a timer). project_id, task_id, and hours are required.4 params▾

Log a duration-based time entry (not a timer). project_id, task_id, and hours are required.

NameTypeRequiredDescription

hoursnumberrequiredDuration in hours (e.g. 1.5 for 1h30m).

project_idintegerrequiredProject id to track time against.

task_idintegerrequiredTask id within the project.

notesstringoptionalOptional notes describing the work.

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.

spent_datestringoptionalDate the time is being logged for (YYYY-MM-DD). Defaults to today.

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

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

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

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

NameTypeRequiredDescription

messagestringrequiredFeedback message text.

harvestmcp_submit_timesheet#Submit a timesheet period for approval. week_of is required (YYYY-MM-DD of any day in the target week).2 params▾

Submit a timesheet period for approval. week_of is required (YYYY-MM-DD of any day in the target week).

NameTypeRequiredDescription

week_ofstringrequiredAny date (YYYY-MM-DD) within the week to submit for approval.

notestringoptionalOptional note to the approver.

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.

currencystringoptionalNew 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.7 params▾

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

NameTypeRequiredDescription

idintegerrequiredExpense id to update.

billablebooleanoptionalWhether the expense is billable.

expense_category_idintegeroptionalNew expense category id.

notesstringoptionalNew notes.

project_idintegeroptionalNew project id.

spent_datestringoptionalNew date (YYYY-MM-DD).

total_costnumberoptionalNew total cost.

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

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

NameTypeRequiredDescription

idintegerrequiredProject id to update.

budgetnumberoptionalNew budget amount.

codestringoptionalNew project code.

ends_onstringoptionalNew end date (YYYY-MM-DD).

is_activebooleanoptionalSet to false to archive the project.

is_billablebooleanoptionalWhether the project is billable.

namestringoptionalNew project name.

notesstringoptionalNew project notes.

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

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

NameTypeRequiredDescription

idintegerrequiredTask id to update.

billable_by_defaultbooleanoptionalWhether the task is billable by default.

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.6 params▾

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

NameTypeRequiredDescription

idintegerrequiredTime entry id to update.

hoursnumberoptionalNew duration in hours.

notesstringoptionalNew notes.

project_idintegeroptionalNew project id.

spent_datestringoptionalNew date (YYYY-MM-DD).

task_idintegeroptionalNew task id.