# Fresha MCP tools

> Every Fresha MCP tool on the Cotlet server: tool names, input schemas, a tools/call example and an example result for each tool.

Source: https://cotlet.dev/docs/mcp/fresha

Docs sections: [Get started](https://cotlet.dev/docs.md) · [REST API](https://cotlet.dev/docs/api.md) · [MCP](https://cotlet.dev/docs/mcp.md) · [SDKs & CLI](https://cotlet.dev/docs/sdks.md) · [Integrations](https://cotlet.dev/docs/integrations.md)

14 tools for Fresha on the Cotlet MCP server. Your agent picks them from tools/list.

- MCP server: `https://cotlet.dev/mcp/v1`
- Connects with: Your own Fresha business account (owner, or a team member whose permissions cover the calendar, clients, reports and wallet)
- Integration page: https://cotlet.dev/integrations/fresha-api-mcp-server

## Endpoints

| Endpoint | Access | Description |
|---|---|---|
| `fresha_list_appointments` | read | Appointments in a date range, with client, services, team member and status. |
| `fresha_find_available_slots` | read | Free start times on one day for one or more services, for anyone or one team member. |
| `fresha_list_clients` | read | Your client list with contact details, last appointment and marketing consent. |
| `fresha_get_client` | read | Client profile: details, notes, allergies, and upcoming and past appointments. |
| `fresha_list_services` | read | Your service menu with categories, durations and prices. |
| `fresha_list_team_members` | read | Bookable team members with their locations and services. |
| `fresha_get_sales_summary` | read | Sales, discounts and refunds from the Sales summary report, for a date range. |
| `fresha_list_payouts` | read | Payouts from your business wallet to your bank, with dates, amounts and fees. |
| `fresha_create_appointment` | write | Book one or more services for a client at a given time. |
| `fresha_reschedule_appointment` | write | Move an appointment to a new time, and optionally to another team member. |
| `fresha_cancel_appointment` | write | Cancel a current or future appointment with one of your cancellation reasons. |
| `fresha_add_client` | write | Create a client profile. Nothing is sent to the client. |
| `fresha_add_client_note` | write | Save a note on a client profile, such as a color formula or preference. |
| `fresha_add_blocked_time` | write | Block time in a team member's calendar for a break, training or admin. |

## List appointments

MCP tool: `fresha_list_appointments`

Access: read.

Lists appointments for the dates you give, ordered by start time. Each one has its client, services, team member and status. Statuses are Booked, Confirmed, Completed, Cancelled and No-show, plus any custom statuses your business created in Settings; custom ones come back under their own name. Pass appointment_id from an item to reschedule_appointment or cancel_appointment. Pass next_cursor back as cursor for the next page.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `from` | date | yes | First day. |
| `to` | date | no | Last day. Default: same as from. |
| `status` | string | no | booked, confirmed, completed, cancelled or no_show, or the name of a custom status. Default: all. |
| `team_member_id` | string | no | Only this team member. |
| `client_id` | string | no | Only this client. |
| `location_id` | string | no | Only this location. Default: all locations. |
| `cursor` | string | no | Next page cursor from the previous call. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "fresha_list_appointments",
    "arguments": {
      "from": "2026-10-01"
    }
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "appointments": [
      {
        "appointment_id": "ap_90311301",
        "client": {
          "client_id": "cl_48213977",
          "name": "Anna Smith"
        },
        "start_at": "2026-10-15T10:00:00+01:00",
        "end_at": "2026-10-15T10:45:00+01:00",
        "services": [
          "Haircut"
        ],
        "team_member": {
          "team_member_id": "tm_5521",
          "name": "Sam"
        },
        "status": "Booked",
        "location_id": "loc_201"
      }
    ],
    "next_cursor": null
  },
  "isError": false
}
```

## Find available slots

MCP tool: `fresha_find_available_slots`

Access: read.

Returns the free start times on one day for the services you list, booked back to back in that order. Each slot names the team member who is free. Pass start_at from a slot to create_appointment or reschedule_appointment. The search covers one day per call.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `service_ids` | string[] | yes | Services from list_services, booked in this order. |
| `date` | date | yes | Day to search. |
| `team_member_id` | string | no | Only this team member. Default: anyone. |
| `location_id` | string | no | Only this location. Default: all locations. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "fresha_find_available_slots",
    "arguments": {
      "service_ids": [
        "service ids"
      ],
      "date": "2026-10-01"
    }
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "date": "2026-10-16",
    "slots": [
      {
        "start_at": "2026-10-16T14:30:00+01:00",
        "end_at": "2026-10-16T15:15:00+01:00",
        "team_member_id": "tm_5521",
        "team_member": "Sam"
      },
      {
        "start_at": "2026-10-16T16:00:00+01:00",
        "end_at": "2026-10-16T16:45:00+01:00",
        "team_member_id": "tm_5521",
        "team_member": "Sam"
      }
    ]
  },
  "isError": false
}
```

## List clients

MCP tool: `fresha_list_clients`

Access: read.

Lists clients, A to Z, with contact details, their last appointment date and marketing consent. The last appointment ignores cancelled and no-show bookings, the same as Fresha's Client insights report. Use last_appointment_before to find clients who have not been in since a date. Card details are never returned. Pages hold up to 500 clients; pass next_cursor back as cursor.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `search` | string | no | Name, email or phone. |
| `last_appointment_before` | date | no | Only clients whose last appointment was before this date. |
| `location_id` | string | no | Only this location. Default: all locations. |
| `limit` | integer | no | 1 to 500. Default: 100. |
| `cursor` | string | no | Next page cursor from the previous call. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "fresha_list_clients",
    "arguments": {}
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "clients": [
      {
        "client_id": "cl_48213977",
        "name": "Anna Smith",
        "email": "anna@example.com",
        "phone": "+44 7700 900123",
        "last_appointment": "2026-06-20",
        "accepts_marketing": true,
        "accepts_sms_marketing": false
      }
    ],
    "next_cursor": "eyJvZmZzZXQiOjEwMH0"
  },
  "isError": false
}
```

## Get client

MCP tool: `fresha_get_client`

Access: read.

Returns one client's profile: contact details, the notes your team saved, allergies, and upcoming and past appointments, newest first. Notes are visible only to your team. Use it before booking or writing to a client.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `client_id` | string | yes | Client ID from list_clients. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "fresha_get_client",
    "arguments": {
      "client_id": "client_8c41d2"
    }
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "client_id": "cl_48213977",
    "name": "Anna Smith",
    "phone": "+44 7700 900123",
    "notes": [
      {
        "text": "Prefers a warm toner, no fragrance.",
        "created_at": "2026-05-14T11:02:00+01:00"
      }
    ],
    "allergies": [],
    "upcoming_appointments": [
      {
        "appointment_id": "ap_90311245",
        "start_at": "2026-10-16T14:30:00+01:00",
        "services": [
          "Haircut"
        ]
      }
    ],
    "past_appointments": [
      {
        "appointment_id": "ap_88120411",
        "start_at": "2026-06-20T11:00:00+01:00",
        "services": [
          "Colour"
        ],
        "status": "Completed"
      }
    ]
  },
  "isError": false
}
```

## List services

MCP tool: `fresha_list_services`

Access: read.

Returns your service menu grouped by category, with duration and price for each service. Prices are in your business currency. Use service_id from an item in find_available_slots and create_appointment.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `location_id` | string | no | Only this location. Default: all locations. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "fresha_list_services",
    "arguments": {}
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "services": [
      {
        "service_id": "sv_1203",
        "name": "Haircut",
        "category": "Hair",
        "duration_minutes": 45,
        "price": "45.00",
        "currency": "GBP"
      },
      {
        "service_id": "sv_1288",
        "name": "Colour",
        "category": "Hair",
        "duration_minutes": 90,
        "price": "85.00",
        "currency": "GBP"
      }
    ]
  },
  "isError": false
}
```

## List team members

MCP tool: `fresha_list_team_members`

Access: read.

Lists the team members who can be booked, with their locations and the services each one offers. Use team_member_id from an item to filter list_appointments or to book with a specific person.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `location_id` | string | no | Only this location. Default: all locations. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "fresha_list_team_members",
    "arguments": {}
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "team_members": [
      {
        "team_member_id": "tm_5521",
        "name": "Sam",
        "locations": [
          "loc_201"
        ],
        "service_ids": [
          "sv_1203",
          "sv_1288"
        ]
      }
    ]
  },
  "isError": false
}
```

## Get sales summary

MCP tool: `fresha_get_sales_summary`

Access: read.

Returns the Sales summary report for the dates you give: items sold, sales, discounts and refunds. Set group_by to split the totals by payment method, discount name or discount type. Tips and service charges are not in this report, because it is built from sale items. Amounts are in your business currency.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `from` | date | yes | First day. |
| `to` | date | no | Last day. Default: same as from. |
| `group_by` | enum | no | payment_method, discount_name or discount_type. Default: no grouping. |
| `location_id` | string | no | Only this location. Default: all locations. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "fresha_get_sales_summary",
    "arguments": {
      "from": "2026-10-13",
      "to": "2026-10-13",
      "group_by": "payment_method",
      "location_id": "loc_201"
    }
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "from": "2026-10-10",
    "to": "2026-10-10",
    "currency": "GBP",
    "groups": [
      {
        "payment_method": "Card",
        "items_sold": 18,
        "sales": "742.00",
        "discounts": "30.00",
        "refunds": "0.00"
      },
      {
        "payment_method": "Cash",
        "items_sold": 7,
        "sales": "266.00",
        "discounts": "10.00",
        "refunds": "45.00"
      }
    ],
    "total": {
      "items_sold": 25,
      "sales": "1008.00",
      "discounts": "40.00",
      "refunds": "45.00"
    }
  },
  "isError": false
}
```

## List payouts

MCP tool: `fresha_list_payouts`

Access: read.

Lists transfers from your business wallet to your bank, newest first. Each has its date, amount, the fees Fresha deducted and the net amount. Scheduled and manual payouts are both included. It works only when Fresha Payments is on, and the account needs the Wallet and card processing permission.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `from` | date | no | Start of the period. Default: 30 days ago. |
| `to` | date | no | End of the period. Default: today. |
| `cursor` | string | no | Next page cursor from the previous call. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "fresha_list_payouts",
    "arguments": {}
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "payouts": [
      {
        "payout_id": "po_77120",
        "type": "scheduled",
        "date": "2026-09-29",
        "amount": "840.00",
        "fees": "12.60",
        "net": "827.40",
        "currency": "GBP"
      },
      {
        "payout_id": "po_76988",
        "type": "manual",
        "date": "2026-09-22",
        "amount": "300.00",
        "fees": "0.50",
        "net": "299.50",
        "currency": "GBP"
      }
    ],
    "next_cursor": null
  },
  "isError": false
}
```

## Create appointment

MCP tool: `fresha_create_appointment`

Access: write. Confirm: waits for the user's OK before it runs.

Books the services you list for a client, back to back, from start_at. The appointment starts as Booked. Without team_member_id it goes to the first team member who is free. Check the time with find_available_slots first; a time that is taken fails. The booking can reach the client. By default you confirm each call; you can switch that off for this tool.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `client_id` | string | yes | Client ID from list_clients. |
| `start_at` | datetime | yes | ISO 8601 with time zone. |
| `service_ids` | string[] | yes | Services from list_services, in order. |
| `team_member_id` | string | no | Team member. Default: first available. |
| `location_id` | string | no | Only this location. Default: all locations. |
| `note` | string | no | Appointment note for your team. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "fresha_create_appointment",
    "arguments": {
      "client_id": "cl_48213977",
      "start_at": "2026-10-16T14:30:00+01:00",
      "service_ids": [
        "sv_1203"
      ],
      "team_member_id": "tm_5521"
    }
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "appointment_id": "ap_90311245",
    "status": "Booked",
    "start_at": "2026-10-16T14:30:00+01:00",
    "end_at": "2026-10-16T15:15:00+01:00",
    "services": [
      {
        "service_id": "sv_1203",
        "name": "Haircut",
        "price": "45.00",
        "currency": "GBP"
      }
    ],
    "team_member": "Sam"
  },
  "isError": false
}
```

## Reschedule appointment

MCP tool: `fresha_reschedule_appointment`

Access: write. Confirm: waits for the user's OK before it runs.

Moves one appointment to a new start time, keeping its services. Set team_member_id to hand it to someone else. Check the new time with find_available_slots first. The move can reach the client. By default you confirm each call; you can switch that off for this tool.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `appointment_id` | string | yes | Appointment ID from list_appointments. |
| `start_at` | datetime | yes | New start, ISO 8601 with time zone. |
| `team_member_id` | string | no | New team member. Default: unchanged. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "fresha_reschedule_appointment",
    "arguments": {
      "appointment_id": "ap_90311301",
      "start_at": "2026-10-15T10:00:00+01:00",
      "team_member_id": "tm_5530"
    }
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "appointment_id": "ap_90311301",
    "status": "Booked",
    "start_at": "2026-10-16T10:00:00+01:00",
    "end_at": "2026-10-16T10:45:00+01:00",
    "team_member": "Sam"
  },
  "isError": false
}
```

## Cancel appointment

MCP tool: `fresha_cancel_appointment`

Access: write. Confirm: waits for the user's OK before it runs.

Cancels one appointment. Fresha only cancels appointments that start in the future, so a past one fails; mark it as a no-show in the app instead. The reason must be one of the cancellation reasons you manage in Fresha. Your payment policy for the appointment applies as it does in the app. For a repeating series, scope picks this appointment or the whole series. By default you confirm each call; you can switch that off for this tool.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `appointment_id` | string | yes | Appointment ID from list_appointments. |
| `reason` | string | yes | Name of one of your cancellation reasons. |
| `notify_client` | boolean | no | Send the client a cancellation message. Default: true. |
| `scope` | enum | no | this_appointment or whole_series, for repeating appointments. Default: this_appointment. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "fresha_cancel_appointment",
    "arguments": {
      "appointment_id": "appointment_8c41d2",
      "reason": "reason"
    }
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "appointment_id": "ap_90311245",
    "status": "Cancelled",
    "reason": "Team member unwell",
    "scope": "this_appointment",
    "client_notified": true
  },
  "isError": false
}
```

## Add client

MCP tool: `fresha_add_client`

Access: write.

Creates a client profile and returns its client_id, which you pass to create_appointment. It sends nothing to the client and reaches no one, so it runs without asking first. Search with list_clients first to avoid a duplicate profile.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `first_name` | string | yes | First name. |
| `last_name` | string | no | Last name. |
| `email` | string | no | Email. |
| `phone` | string | no | Mobile number with country code. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "fresha_add_client",
    "arguments": {
      "first_name": "first name"
    }
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "client_id": "cl_48213990",
    "name": "Maya Patel",
    "phone": "+44 7700 900456"
  },
  "isError": false
}
```

## Add client note

MCP tool: `fresha_add_client_note`

Access: write.

Adds a simple note to a client profile. Notes are private: only your team sees them, never the client. Fresha cannot recover a deleted note, so the agent adds notes and never deletes them. It reaches no one, so it runs without asking first.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `client_id` | string | yes | Client ID from list_clients. |
| `text` | string | yes | Note text. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "fresha_add_client_note",
    "arguments": {
      "client_id": "client_8c41d2",
      "text": "text"
    }
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "client_id": "cl_48213977",
    "note_id": "nt_5521",
    "created_at": "2026-10-11T09:12:00+01:00"
  },
  "isError": false
}
```

## Add blocked time

MCP tool: `fresha_add_blocked_time`

Access: write.

Blocks a time range in one team member's calendar, so no one can book it. Use title for a reason such as one of your blocked time types, and description for a note your team sees. It reaches no client and is removed in Fresha in one step, so it runs without asking first.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `team_member_id` | string | yes | Team member from list_team_members. |
| `start_at` | datetime | yes | ISO 8601 with time zone. |
| `end_at` | datetime | yes | ISO 8601 with time zone. |
| `title` | string | no | Reason, e.g. one of your blocked time types. |
| `description` | string | no | Note your team sees on the block. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "fresha_add_blocked_time",
    "arguments": {
      "team_member_id": "team_member_8c41d2",
      "start_at": "2026-10-01T09:00:00Z",
      "end_at": "2026-10-01T09:00:00Z"
    }
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "blocked_time_id": "bt_3302",
    "team_member": "Sam",
    "start_at": "2026-10-14T13:00:00+01:00",
    "end_at": "2026-10-14T14:00:00+01:00",
    "title": "Training"
  },
  "isError": false
}
```