How to Connect Zalo Official Account to Cursor via MCP

💡 No install? Use cloud.anythingmcp.com directly. Sign in, click Connectors → Zalo Official Account, paste your credentials, mint an MCP API key and you're done. No Docker, no git clone, no local server.

Zalo Official Account + Cursor

Zalo Official Account (Vietnam): OA profile and message quota, followers and users with their details and labels, recent chats and conversations, consultation messages with text or an image, and the OA's articles. Uses a pasted OA access token, valid about 25 hours.

Prerequisites

See the full setup instructions baked into the connector (visible in the in-app store when you select the connector). The required environment variables for this connector are:

ZALO_OA_ACCESS_TOKEN

Step 1 — Get credentials

Setting up takes about 5 minutes, and the token has to be renewed every day (see below). You need a Zalo Official Account and an OA admin who approves permissions.

1. At https://developers.zalo.me create an app or open yours, link it to your Official Account and, under Official Account > OA permissions, request the permission groups the connector uses: OA information management, user information management, user message management, sending messages and notifications via OA, and article management. An OA admin approves them.
2. Open Tools > API Explorer (https://developers.zalo.me/tools/explorer), pick your app, choose the access token type OA Access Token, pick the OA, allow the requested permissions and copy the access token.
3. Paste it into ZALO_OA_ACCESS_TOKEN. It is sent in the access_token header that Zalo requires.
4. Install the connector and run zalo_oa_get_oa_info to check it.

The token lasts about 25 hours. Zalo renews OA access tokens only through its own OAuth v4 flow, which AnythingMCP cannot run for this connector, so the token is pasted. When calls answer error -216 or -220, create a new token in API Explorer and save it in the connector settings. If you renew tokens in your own system, you can write each new token into ZALO_OA_ACCESS_TOKEN through the AnythingMCP API.

What it reads: the OA profile (name, id, verification, followers, service package) and its message quota; the users who follow or talked to the OA, 50 per page, with filters by label, last interaction or follower status; one user's name, alias, follower status, last interaction date, labels, notes and shared information; the labels of the OA; the latest messages across all chats and the messages with one user, 10 per call; and the OA's articles and videos with their body.

What it writes: user details (alias, your own customer id and shared information) and labels: the AI puts a label on a user, creating it when it is missing, or takes it off. zalo_oa_send_text sends a consultation text, optionally quoting the user's message, and zalo_oa_send_image a consultation message with one image. Both reach a real person, so the AI shows the text and waits for your yes.

When a consultation message can be sent: only to a user who interacted with the OA in the last 7 days. From 1 January 2026, consultation messages within 48 hours of the user's last interaction are free and unlimited; later ones use the OA package quota or are charged. zalo_oa_get_user_quota tells the AI what can still be sent to a user. Error -230 or -232 means the user has not interacted recently enough, -213 that the user does not follow the OA.

Switched off at install: zalo_oa_delete_tag, which removes a label from the OA and from every user who has it, and cannot be undone.

Formats: every answer has error (0 = success) and message, with the payload in data; errors arrive with HTTP 200 and a negative error. User, OA and message ids are long digit strings. In a message, src is 1 when the user sent it and 0 when the OA did. Message times are Unix milliseconds, and user_last_interaction_date is dd/MM/yyyy.

Limits: 4,000 requests per minute per app, plus a per-OA limit that depends on the OA package; error -32 means waiting for the next minute. The user list reaches the first 10,000 users.

Common errors: -216 or -220 means an invalid or expired token (paste a new one), -223 a permission the OA has not granted to the app, -224 a feature the OA package does not include, -201 an invalid parameter, and -211 a quota that is used up.

The connector does not send transaction, promotion or ZNS template messages, files or stickers, and does not cover group chats, calls, article creation or the OA shop. Webhooks are configured in the Zalo app settings.

Step 2 — Install the adapter

curl -fsSL https://raw.githubusercontent.com/HelpCode-ai/anythingmcp/main/docker-compose.quickstart.yml -o docker-compose.yml
printf 'JWT_SECRET=%s\nENCRYPTION_KEY=%s\n' "$(openssl rand -hex 32)" "$(openssl rand -hex 32)" > .env
docker compose up -d

Step 3 — Add the connector in Cursor

Your server URL: in AnythingMCP, open MCP Servers → the server this connector is on, and copy its URL (https://cloud.anythingmcp.com/mcp/…). Use it wherever this guide shows YOUR_SERVER_ID.

Cursor reads MCP servers from ~/.cursor/mcp.json. Add this entry:

{
  "mcpServers": {
    "anythingmcp": {
      "url": "https://cloud.anythingmcp.com/mcp/YOUR_SERVER_ID",
      "headers": { "X-API-Key": "YOUR_MCP_API_KEY" }
    }
  }
}

1. Create an MCP API key in AnythingMCP under MCP Servers → your server → API keys, and paste it in place of YOUR_MCP_API_KEY.
2. Save the file and restart Cursor.
3. Open Cursor → Settings → MCP and check that anythingmcp is listed and connected.
4. Start chatting: the agent can now call the Zalo Official Account tools.

Available tools

Example prompts

• "Which users messaged the OA in the last 24 hours, and what did they ask?"
• "Show my conversation with this user and draft a reply to their last question."
• "Put the label delivery-question on everyone who asked about delivery this week."
• "How much consultation message quota does the OA have left?"
• "List the five most viewed articles of the OA."

FAQ

Does Cursor support custom MCP servers on the free tier? Yes, MCP is available on Hobby, Pro and Business plans.

Next steps

• Connector landing page
• Connect to Claude
• Connect to ChatGPT
• Connect to Gemini
• Connect to Meta Muse
• Connect to Microsoft Copilot