HERO Software API and MCP server Let your AI agent write the quote and chase the invoice.

ToolWhat it doesAccess

• list_projects List projects in the account with customer, project number and status. read

  Returns projects as HERO shows them in the project overview, with the internal project ID, the project number, the customer and the status. Use the ID in get_project and the other project tools. A long list comes in pages: follow next_cursor until it is empty.

  MCP callhero_software_read → list_projects

  REST endpointGET https://cotlet.dev/api/v1/hero-software/projects

  Parameters

  Parameters: list_projects

  Name	Type	Description
  query string	string	Part of a project name, number or customer name.
  cursor string	string	Next page cursor from the previous call.

  Example response

  {
    "projects": [
      {
        "project_id": "48213",
        "number": "P-2026-0187",
        "name": "Keller bathroom tap",
        "customer": "Anna Keller",
        "status": "In progress"
      },
      {
        "project_id": "48190",
        "number": "P-2026-0184",
        "name": "Brandt heating service",
        "customer": "Brandt GmbH",
        "status": "Quote sent"
      }
    ],
    "next_cursor": null
  }

• get_project Read one project with its customer, documents, appointments and logbook. read

  Returns the project data, the documents saved to the project (quotes, order confirmations, invoices) with their IDs, its appointments and the logbook entries, newest first. Use it before a reminder or an invoice to see what already exists for the job.

  MCP callhero_software_read → get_project

  REST endpointGET https://cotlet.dev/api/v1/hero-software/projects/{project_id}

  Parameters

  Parameters: get_project

  Name	Type	Description
  project_id string required	string	Project ID from list_projects.

  Example input

  {
    "project_id": "project_8c41d2"
  }

  Example response

  {
    "project_id": "48213",
    "number": "P-2026-0187",
    "name": "Keller bathroom tap",
    "customer": "Anna Keller",
    "status": "In progress",
    "documents": [
      {
        "document_id": "d-7731",
        "type": "quote",
        "number": "A-2026-0301",
        "total": 875.84
      }
    ],
    "appointments": [
      {
        "appointment_id": "e-5520",
        "title": "Fit tap set",
        "starts_at": "2026-11-18T08:00:00+01:00"
      }
    ],
    "logbook": [
      {
        "date": "2026-11-14",
        "text": "Quote sent, customer wants to start on 18 Nov."
      }
    ]
  }

• list_contacts Search the customer index by name, company or address. read

  Returns contacts from the customer index with their ID, name, address, phone and email. Check it before create_contact so the same customer is not added twice.

  MCP callhero_software_read → list_contacts

  REST endpointGET https://cotlet.dev/api/v1/hero-software/contacts

  Parameters

  Parameters: list_contacts

  Name	Type	Description
  query string	string	Part of a name, company or street.
  cursor string	string	Next page cursor from the previous call.

  Example response

  {
    "contacts": [
      {
        "contact_id": "c-2201",
        "name": "Anna Keller",
        "address": "Lindenweg 4, 30159 Hannover",
        "phone": "+49 511 555 0142",
        "email": "anna.keller@example.com"
      }
    ],
    "next_cursor": null
  }

• create_contact Add a customer to the customer index. write

  Creates the contact and returns its ID. It changes only your own HERO account and reaches no customer, so it does not wait for your OK. Run list_contacts first to avoid a duplicate.

  MCP callhero_software_write → create_contact

  REST endpointPOST https://cotlet.dev/api/v1/hero-software/contacts

  Parameters

  Parameters: create_contact

  Name	Type	Description
  name string required	string	Full name or company name.
  address string	string	Street, postcode and city.
  phone string	string	Phone number.
  email string	string	Email address.

  Example input

  {
    "name": "Jane Doe"
  }

  Example response

  {
    "contact_id": "c-2201",
    "name": "Anna Keller",
    "created": true
  }

• create_project Open a project for a contact. write

  Creates the project for the contact and returns its ID and project number. It reaches no one outside your account, so it does not wait for your OK.

  MCP callhero_software_write → create_project

  REST endpointPOST https://cotlet.dev/api/v1/hero-software/contacts/{contact_id}/projects

  Parameters

  Parameters: create_project

  Name	Type	Description
  contact_id string required	string	Contact ID from list_contacts or create_contact.
  name string required	string	Project name.
  note string	string	First note on the project.

  Example input

  {
    "contact_id": "contact_8c41d2",
    "name": "Jane Doe"
  }

  Example response

  {
    "project_id": "48213",
    "number": "P-2026-0187",
    "name": "Keller bathroom tap",
    "status": "New"
  }

• add_logbook_entry Add a note to a project logbook. write

  Adds the entry to the project logbook under your name. It reaches no one, so it does not wait for your OK.

  MCP callhero_software_write → add_logbook_entry

  REST endpointPOST https://cotlet.dev/api/v1/hero-software/projects/{project_id}/logbook-entries

  Parameters

  Parameters: add_logbook_entry

  Name	Type	Description
  project_id string required	string	Project ID from list_projects.
  text string required	string	The note.

  Example input

  {
    "project_id": "project_8c41d2",
    "text": "text"
  }

  Example response

  {
    "project_id": "48213",
    "logged": true,
    "text": "Tap fitted, old valve left with the customer."
  }

ToolWhat it doesAccess

• list_documents List quotes, order confirmations, invoices and delivery notes with number, customer, total and status. read

  Returns documents with their ID, type, number, customer, project, total and the status HERO shows. With overdue_only the list holds unpaid invoices past their due date, with the days overdue. Documents come in pages: follow next_cursor.

  MCP callhero_software_read → list_documents

  REST endpointGET https://cotlet.dev/api/v1/hero-software/documents

  Parameters

  Parameters: list_documents

  Name	Type	Description
  type string	string	quote, order_confirmation, invoice or delivery_note. Leave empty for all.
  project_id string	string	Only documents of this project.
  overdue_only boolean	boolean	Only invoices past their due date and not paid.
  cursor string	string	Next page cursor from the previous call.

  Example response

  {
    "documents": [
      {
        "document_id": "d-7702",
        "type": "invoice",
        "number": "R-2026-0412",
        "customer": "Brandt GmbH",
        "project_id": "48190",
        "total": 1190,
        "due_date": "2026-10-30",
        "days_overdue": 15
      },
      {
        "document_id": "d-7731",
        "type": "quote",
        "number": "A-2026-0301",
        "customer": "Anna Keller",
        "project_id": "48213",
        "total": 875.84,
        "status": "sent"
      }
    ],
    "next_cursor": null
  }

• get_document Read one document with its line items, tax and totals. read

  Returns the line items with quantity, unit, unit price and tax rate, the net, tax and gross totals, the customer and the project. Use it to check a quote before it becomes an invoice.

  MCP callhero_software_read → get_document

  REST endpointGET https://cotlet.dev/api/v1/hero-software/documents/{document_id}

  Parameters

  Parameters: get_document

  Name	Type	Description
  document_id string required	string	Document ID from list_documents.

  Example input

  {
    "document_id": "document_8c41d2"
  }

  Example response

  {
    "document_id": "d-7731",
    "type": "quote",
    "number": "A-2026-0301",
    "customer": "Anna Keller",
    "project_id": "48213",
    "items": [
      {
        "title": "Labour",
        "quantity": 8,
        "unit": "h",
        "unit_price": 62,
        "vat_rate": 19
      },
      {
        "title": "Tap set, chrome",
        "quantity": 1,
        "unit": "pc",
        "unit_price": 240,
        "vat_rate": 19
      }
    ],
    "net": 736,
    "vat": 139.84,
    "gross": 875.84
  }

• create_quote Draft a quote on a project from line items. write

  Saves the quote to the project and returns its number and totals. It is not sent: it stays in the project until send_document. Prices not in your article master data are used as you give them; the agent never invents a price.

  MCP callhero_software_write → create_quote

  REST endpointPOST https://cotlet.dev/api/v1/hero-software/projects/{project_id}/quotes

  Parameters

  Parameters: create_quote

  Name	Type	Description
  project_id string required	string	Project ID from list_projects.
  items array required	array	Line items: title, quantity, unit, unit_price, vat_rate. Optional article_id to take an item from the article master data.
  intro string	string	Text above the items.

  Example input

  {
    "project_id": "48213",
    "items": [
      {
        "title": "Labour",
        "quantity": 8,
        "unit": "h",
        "unit_price": 62,
        "vat_rate": 19
      },
      {
        "title": "Tap set, chrome",
        "quantity": 1,
        "unit": "pc",
        "unit_price": 240,
        "vat_rate": 19
      }
    ],
    "intro": "Thank you for your inquiry. We offer the following work:"
  }

  Example response

  {
    "document_id": "d-7731",
    "type": "quote",
    "number": "A-2026-0301",
    "net": 736,
    "vat": 139.84,
    "gross": 875.84,
    "sent": false
  }

• create_invoice_from_quote Turn a quote or order confirmation into an invoice. writeAsks first

  Uses the convert function HERO offers on a quote: customer, items and prices carry over, and the invoice is saved to the project. It is not sent. It creates a financial document, so you confirm each call and check the numbers first. By default you confirm each call; you can switch that off for this tool.

  MCP callhero_software_write → create_invoice_from_quote

  REST endpointPOST https://cotlet.dev/api/v1/hero-software/documents/{document_id}/invoice-from-quotes

  Parameters

  Parameters: create_invoice_from_quote

  Name	Type	Description
  document_id string required	string	ID of the quote or order confirmation from list_documents.

  Example input

  {
    "document_id": "document_8c41d2"
  }

  Example response

  {
    "document_id": "d-7760",
    "type": "invoice",
    "number": "R-2026-0420",
    "from_document_id": "d-7731",
    "gross": 875.84,
    "sent": false
  }

• send_document Email a quote or invoice to the customer. writeAsks first

  Sends the document to the customer's email address on the contact. The email reaches the customer and cannot be recalled. By default you confirm each call; you can switch that off for this tool.

  MCP callhero_software_write → send_document

  REST endpointPOST https://cotlet.dev/api/v1/hero-software/documents/{document_id}

  Parameters

  Parameters: send_document

  Name	Type	Description
  document_id string required	string	Document ID from list_documents.
  subject string	string	Email subject. Empty uses the default.
  message string	string	Email text.

  Example input

  {
    "document_id": "document_8c41d2"
  }

  Example response

  {
    "document_id": "d-7731",
    "sent_to": "anna.keller@example.com",
    "sent_at": "2026-11-14T10:12:00+01:00"
  }

• send_payment_reminder Send a payment reminder for an unpaid invoice. writeAsks first

  Creates the reminder from the invoice, as HERO does for payment reminders, and emails it to the customer. It asks for money from a customer, so check the project logbook first. By default you confirm each call; you can switch that off for this tool.

  MCP callhero_software_write → send_payment_reminder

  REST endpointPOST https://cotlet.dev/api/v1/hero-software/documents/{document_id}/payment-reminders

  Parameters

  Parameters: send_payment_reminder

  Name	Type	Description
  document_id string required	string	Invoice ID from list_documents with overdue_only.
  message string	string	Extra text for the customer.

  Example input

  {
    "document_id": "document_8c41d2"
  }

  Example response

  {
    "document_id": "d-7790",
    "type": "payment_reminder",
    "invoice_number": "R-2026-0412",
    "sent_to": "office@brandt.example",
    "sent_at": "2026-11-14T10:20:00+01:00"
  }

ToolWhat it doesAccess

• list_appointments List calendar appointments in a date range. read

  Returns the appointments from the HERO calendar in the range, soonest first, with title, time, project, customer address and the people assigned. Single and recurring appointments both appear.

  MCP callhero_software_read → list_appointments

  REST endpointGET https://cotlet.dev/api/v1/hero-software/appointments

  Parameters

  Parameters: list_appointments

  Name	Type	Description
  from string required	string	First day, YYYY-MM-DD.
  to string required	string	Last day, YYYY-MM-DD.
  cursor string	string	Next page cursor from the previous call.

  Example input

  {
    "from": "from",
    "to": "to"
  }

  Example response

  {
    "appointments": [
      {
        "appointment_id": "e-5520",
        "title": "Fit tap set",
        "starts_at": "2026-11-18T08:00:00+01:00",
        "project_id": "48213",
        "address": "Lindenweg 4, 30159 Hannover",
        "assigned": [
          "Jonas"
        ]
      }
    ],
    "next_cursor": null
  }

• list_tasks List open or completed tasks, with project and assignee. read

  Returns the tasks HERO shows in its task overview, with title, project, assignee and due date. Use state open for a daily briefing.

  MCP callhero_software_read → list_tasks

  REST endpointGET https://cotlet.dev/api/v1/hero-software/tasks

  Parameters

  Parameters: list_tasks

  Name	Type	Description
  state string	string	open or completed. Leave empty for both.
  project_id string	string	Only tasks of this project.
  cursor string	string	Next page cursor from the previous call.

  Example response

  {
    "tasks": [
      {
        "task_id": "t-9120",
        "title": "Order tap set",
        "project_id": "48213",
        "assignee": "Jonas",
        "due_date": "2026-11-17",
        "state": "open"
      }
    ],
    "next_cursor": null
  }

• create_appointment Put an appointment in the HERO calendar. write

  Creates a single appointment on the project and shows it in the calendar and the planning board. It does not email the customer, so it does not wait for your OK.

  MCP callhero_software_write → create_appointment

  REST endpointPOST https://cotlet.dev/api/v1/hero-software/projects/{project_id}/appointments

  Parameters

  Parameters: create_appointment

  Name	Type	Description
  project_id string required	string	Project ID from list_projects.
  title string required	string	Appointment title.
  starts_at string required	string	Start, ISO 8601 with offset.
  ends_at string required	string	End, ISO 8601 with offset.
  assigned array	array	Names of team members to assign.

  Example input

  {
    "project_id": "project_8c41d2",
    "title": "title",
    "starts_at": "starts at",
    "ends_at": "ends at"
  }

  Example response

  {
    "appointment_id": "e-5520",
    "title": "Fit tap set",
    "starts_at": "2026-11-18T08:00:00+01:00",
    "assigned": [
      "Jonas"
    ]
  }