> For the complete documentation index, see [llms.txt](https://help.zaapi.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.zaapi.com/developers/mcp.md).

# MCP

The Zaapi MCP server connects AI assistants — Claude, Claude Code, Cursor and any other MCP-compatible tool — directly to your Zaapi workspace. Once it's installed, you can ask your assistant to work with your real inbox in plain language: find tickets, read conversations, look up contacts, update custom fields, leave internal notes, even reply to customers.

MCP (Model Context Protocol) is an open standard for connecting AI assistants to external tools and data. The Zaapi MCP server runs on your own machine and talks to the [Zaapi Open API](https://openplatform.zaapi.co) using an API key you create. Your data stays between your machine, your assistant and Zaapi.

### What you can do with it

A few things people use it for:

* **Triage** — "Show me every open ticket where the customer has been waiting more than four hours."
* **Context before replying** — "Summarise this conversation and tell me what the last agent promised."
* **Reporting** — "How many tickets did the support team close last week, and how many converted?"
* **Bulk lookups** — "Find every contact who mentioned refunds this month and list their phone numbers."
* **Data cleanup** — "Set the Customer Tier field to Gold for these 12 contacts."
* **Drafting** — "Draft a reply to this customer, then leave it as an internal note so I can review it."

### Before you start

You'll need:

* **Node.js 20 or later** on your machine. Check with `node --version`
* **A Zaapi API key** — follow [these instructions](/developers/authentication.md#step-1-create-an-api-key) to create one
* **An MCP-compatible assistant** — Claude Desktop, Claude Code, Cursor, or anything else that supports MCP.

### Install the server

The configuration is the same everywhere. Replace `zaapi_***` with the key you just created.

```json
{
  "mcpServers": {
    "zaapi": {
      "command": "npx",
      "args": ["-y", "@zaapi/open-api-mcp"],
      "env": {
        "ZAAPI_API_KEY": "zaapi_***"
      }
    }
  }
}
```

#### Claude Desktop

1. Open **Settings → Developer → Edit Config**. This opens `claude_desktop_config.json`.
2. Paste the block above. If the file already has an `mcpServers` object, add the `"zaapi"` entry inside it rather than replacing the whole file.
3. Save, then quit and reopen Claude Desktop completely.
4. The Zaapi tools appear in the tools menu in the chat input.

#### Claude Code

Run this in your terminal:

```bash
claude mcp add zaapi --env ZAAPI_API_KEY=zaapi_*** -- npx -y @zaapi/open-api-mcp
```

Add `--scope user` to make it available in every project rather than just the current one. Check it registered with:

```bash
claude mcp list
```

#### Cursor

1. Open **Settings → MCP → Add new MCP server**, or create the config file directly:
   * Project only: `.cursor/mcp.json` in your repository
   * All projects: `~/.cursor/mcp.json`
2. Paste the block above.
3. Restart Cursor. The server appears under Settings → MCP with a green dot when it's connected.

#### VS Code (GitHub Copilot)

Create `.mcp.json` in your workspace root, or use **MCP: Add Server** from the command palette. VS Code nests servers under `servers` rather than `mcpServers`:

```json
{
  "servers": {
    "zaapi": {
      "command": "npx",
      "args": ["-y", "@zaapi/open-api-mcp"],
      "env": {
        "ZAAPI_API_KEY": "zaapi_***"
      }
    }
  }
}
```

#### Other MCP clients

Any client that supports stdio MCP servers will work. Point it at the command `npx` with arguments `-y @zaapi/open-api-mcp`, and set the `ZAAPI_API_KEY` environment variable to your key.

### Step 3 — Check it's working

Ask your assistant:

> List my connected Zaapi accounts.

You should get back the channel inboxes on your store — your LINE OA, WhatsApp number, Shopee shop and so on. If that works, the key and the connection are both good.