io.github.Mad-Man-Dan/karbon-mcp-server

Add one or more users to a team by their UserKeys (find them with list_users). Users already on the team are skipped. Team membership can affect work visibility and assignment — confirm with the user before changing it.

Create a new client group in Karbon. Members are existing contacts and/or organizations.

Create a new person contact in Karbon.

Create a new custom field definition for the whole Karbon tenant. This changes the firm's shared configuration, not just one record — state the field name, type, and visibility to the user and get their explicit confirmation before calling.

Create a note in Karbon, optionally linked to work items, contacts, organizations, or client groups via timelines. Notes linked to a work item also appear on the client's timeline.

Create a new organization contact in Karbon.

Create a new work item in Karbon. WorkType and status values are tenant-specific — call get_tenant_settings first if unsure.

Create a recurring work schedule from an existing work item. The schedule will automatically generate new work items on the recurrence you set — confirm the recurrence details with the user before calling. Note: RecurrenceFrequency cannot be changed after creation.

DESTRUCTIVE AND IRREVERSIBLE: deleting a custom field definition permanently removes the field AND every value stored in it across all contacts, organizations, and client groups in the tenant. Never call this without first telling the user exactly which field will be deleted (by name, via list_custom_fields) and receiving their explicit confirmation for that specific field.

Download a Karbon file to a local path on the machine running this MCP server. Get the DownloadUrl from list_entity_files first — download links expire after 15 minutes, so re-list if the download fails with an auth error. Ask the user where to save before writing outside a temp directory, and never overwrite a file the user didn't ask you to replace.

Get a single business card by BusinessCardKey. Business cards hold the contact details (email, phone, address, websites) of a contact, organization, or client group. Find the key by expanding BusinessCards on get_contact / get_organization / get_client_group.

Get a single client group by ClientGroupKey — or by your own UserDefinedIdentifier — optionally expanding related data (BusinessCard, ClientTeam). Includes the group's members (contacts and organizations). Provide exactly one of clientGroupKey or userDefinedIdentifier.

Get a single comment by its CommentKey. Comments appear on work item and client timelines alongside notes.

Get a single person contact by ContactKey — or by your own UserDefinedIdentifier — optionally expanding related data (BusinessCards, AccountingDetail, ClientTeam). Provide exactly one of contactKey or userDefinedIdentifier.

Get the custom field values set on a specific entity (contact, organization, or client group) by its entity key.

Get the estimate summary for a work item (read-only): budgeted vs. actual time and value. Useful for 'are we over budget on this job' questions — pair with list_time_entries for detail.

Get a single invoice by InvoiceKey (read-only), optionally expanding related data (LineItems, Payments, Data).

Get a single note by its NoteID.

Get a single organization by OrganizationKey — or by your own UserDefinedIdentifier — optionally expanding related data (BusinessCards, AccountingDetail, ClientTeam, Contacts). Provide exactly one of organizationKey or userDefinedIdentifier.

Get a single payment by PaymentKey (read-only).

Get a single team by TeamKey, including its members (users and sub-teams).

Get this Karbon account's configuration: valid work statuses (secondary statuses), work types, and contact types. Call this before creating or updating work items or contacts with tenant-specific values.

Get a single individual time entry by its IndividualTimeEntryKey (read-only).

Get a single timesheet by TimesheetKey, optionally expanding TimeEntries.

Get a single Karbon user by their UserId.

Get a single work item by WorkItemKey.

Get a recurring work schedule by WorkScheduleKey — the recurrence rules that automatically generate work items.

Get a single work template by WorkTemplateKey, including its task and section structure.

List or search client groups in Karbon. Supports OData filtering, e.g. filter: "contains(FullName,'Smith Family')" or "UserDefinedIdentifier eq 'ABC123'".

List or search person contacts in Karbon. Supports OData filtering, e.g. filter: "contains(FullName,'Smith')" or "ContactType eq 'Client'".

List all custom field definitions for the Karbon tenant — field names, types (Text, Number, Date, Boolean, Colleague, ListSingleSelect, ListMultipleSelect), list options, and which entities they apply to.

List the files attached to a work item, contact, or organization — name, size, mime type, created date, and a DownloadUrl usable with download_file. Download links expire 15 minutes after this call.

List invoices in Karbon (read-only). Supports OData filtering, e.g. filter: "InvoiceStatus eq 'AwaitingPayment'" or "TotalAmountDue gt 0". Statuses: Approved, AwaitingPayment, Paid, Exported, Voided.

List or search organization contacts in Karbon. Supports OData filtering, e.g. filter: "contains(FullName,'Acme')".

List payments recorded against invoices in Karbon (read-only). Supports pagination only — the Payments endpoint does not accept OData filters.

List teams in Karbon (read-only). Supports OData filtering, e.g. filter: "contains(Name,'Tax')".

List individual time entries (read-only). Useful for reporting on time logged against clients or work items.

List timesheets (read-only). Useful filters: "StartDate ge 2026-07-01", "UserKey eq '...'".

List Karbon users (team members) on this account.

List or search work items (jobs/engagements) in Karbon. Useful filters: "PrimaryStatus eq 'InProgress'", "AssigneeEmailAddress eq 'user@firm.com'", "DueDate lt 2026-08-01". PrimaryStatus values: Planned, ReadyToStart, InProgress, Waiting, Completed.

List work templates available on this account. Use a WorkTemplateKey with create_work_item to create templated work.

Remove a user from a team by their UserKey. Team membership can affect work visibility and assignment — confirm with the user before changing it.

Set custom field values on an entity (contact, organization, or client group). Use list_custom_fields for the available definitions and get_custom_field_values to see what's currently set. Values are always passed as an array of strings, even for single values.

Update a business card (full replace via PUT) — this is how you change a contact's, organization's, or client group's email addresses, phone numbers, and addresses. Fetch the card first with get_business_card and send back the complete card with your changes, since omitted fields are cleared.

Update fields on an existing client group (partial update via PATCH). Only include the fields you want to change.

Update fields on an existing person contact (partial update via PATCH). Only include the fields you want to change.

Update fields on an existing organization (partial update via PATCH). Only include the fields you want to change.

Update fields on an existing work item (partial update via PATCH). Only include the fields you want to change.

Update a work schedule (partial via PATCH). The API only supports changing the end date and the assignee here. Note: changing AssigneeUserKey reassigns every not-yet-started work item the schedule has generated — confirm with the user first.

Upload a file to Karbon and attach it to a work item, contact, organization, or client group (at least one key is required). SIZE LIMITS: keep uploads small — Karbon rejects oversized uploads, and this server reads the whole file into memory. Prefer filePath (a path on the machine running this MCP server) whenever possible; only use contentBase64 for small files (roughly under 1 MB), because base64 inflates data ~33% and large payloads can exceed the AI client's message limits or be truncated mid-transfer. If a file seems large (tens of MB or more), tell the user to upload it through Karbon's own UI instead. SECURITY: only upload files the user explicitly pointed you to. Never upload configuration files, credential stores, environment files, keys, or anything the user has not named — uploading puts the file's contents in the Karbon tenant.