Model Context Protocol · mcp.merko.ai

Merko MCP Server

Connect Claude Desktop, Claude Code, Cursor, and ChatGPT directly to your Merko account. Manage campaigns, audiences, leads, templates, and images from natural language — securely via OAuth 2.0.

https://mcp.merko.ai/mcp

Connect in 2 minutes → Explore tools

ℹ️

The Merko MCP Server uses OAuth 2.0 Dynamic Client Registration. Your AI client registers automatically, opens your browser for Merko login, and requests scoped access — no manual tokens or secrets.

The MCP server gives any compliant AI assistant a standardized way to:

Access account and profile information
List, analyze, and create marketing campaigns
Browse audiences, segments, and recipient lists
Create, update, and delete lead profiles
Upload images to Merko CDN via URL or base64
Create and retrieve branded HTML email templates

📋Prerequisites

1

A Merko account

You need an active account at app.merko.ai. Your existing login is used for OAuth authorization.

2

An MCP-compatible client

Claude Desktop, Claude Code, Cursor, ChatGPT, or any client with OAuth 2.0 support. See Claude Desktop, Claude Code, Cursor, ChatGPT.

3

MCP server URL

Use https://mcp.merko.ai/mcp — the same URL for every Merko workspace.

⚡What You Can Do

Once connected, your assistant can act across six functional areas:

👤

Account

Retrieve account details and profile via natural language.

📣

Campaigns

List campaigns, view stats, and create new campaigns with audience + template.

👥

Audiences

Browse groups, inspect segments, and list campaign recipients.

🗂️

Leads & Profiles

Full CRUD on profiles — get, create, update, delete with contact details.

🖼️

Images

Upload images to Merko CDN by URL or base64 — returns hosted URL.

✉️

Email Templates

Create branded HTML templates with name, tag, HTML, and thumbnail.

🔐Authentication

Merko MCP uses OAuth 2.0 with PKCE and Dynamic Client Registration. Modern clients handle the entire flow automatically — no manual token management.

✅

Zero manual setup. Claude Desktop, Claude Code, and ChatGPT will prompt you to log in via the browser when you first connect.

How it works

1

Client Registration

Client calls POST /register — server returns client_id.

2

Authorization

Client redirects to GET /authorize → Merko hosted login. Approve access.

3

Token Exchange

Client exchanges code at POST /token via PKCE. Receives access + refresh tokens.

4

Authenticated Calls

Client sends Authorization: Bearer <token> with every POST /mcp.

ℹ️

Clients auto-discover OAuth endpoints from /.well-known/oauth-authorization-server. No secrets, no manual refresh — tokens are renewed automatically.

🌐Connection — HTTP Transport

Streamable HTTP is the transport for all modern MCP clients.

POST/mcpStreamable HTTP — primary endpoint

ℹ️

Every /mcp request must include a valid bearer token in the Authorization header.

HTTP Request

POST /mcp HTTP/1.1
Host: mcp.merko.ai
Authorization: Bearer <access_token>
Content-Type: application/json

🖥️Claude Desktop

Add Merko in Claude → Connectors.

1

Open Connectors

Go to Claude → + button under chatbox → Connectors → Add Custom Connector.

2

Paste MCP URL

Enter https://mcp.merko.ai/mcp in the MCP URL field.

3

Authorize via browser

Log in to Merko and approve access. Tools appear instantly in your next chat.

💻Claude Code

One command to register:

Shell

claude mcp add --transport http merko https://mcp.merko.ai/mcp

Or share via .mcp.json at project root:

.mcp.json

{
  "mcpServers": {
    "Merko": {
      "type": "http",
      "url":  "https://mcp.merko.ai/mcp"
    }
  }
}

💡

Run claude mcp list to verify. Start a new session to use Merko tools.

⚡Cursor

Cursor supports MCP natively.

1

Open Settings

Go to Cursor → Settings → MCP (or Cmd/Ctrl + Shift + J → “MCP”).

2

Add server

Click + Add new MCP server, choose Type: HTTP, paste https://mcp.merko.ai/mcp.

3

Authorize

Browser will open for Merko login. Approve to complete OAuth.

4

Use it

New chat → try: “List my Merko campaigns”.

MCP Server URL

https://mcp.merko.ai/mcp

Or .cursor/mcp.json:

.cursor/mcp.json

{
  "mcpServers": {
    "Merko": {
      "type": "http",
      "url":  "https://mcp.merko.ai/mcp"
    }
  }
}

💡

Green dot = connected. Red = check URL and reconnect.

🤖ChatGPT

Via ChatGPT Apps (Plus, Team, Enterprise). Your assistant can manage Merko campaigns in natural language.

⚠️

Confirm Apps availability at help.openai.com for your plan.

1

Open Apps

Go to Settings → Apps in ChatGPT web.

2

Enable developer mode

In Advanced settings turn on Developer mode.

3

Create app

Click Create App, enter https://mcp.merko.ai/mcp, choose OAuth.

4

Connect & authorize

Connect the app and log in via browser prompt.

5

New conversation

New chat → enable Merko via + below the box → try “Show me my Merko campaigns”.

💡

Tip: Include IDs: “Get stats for campaign abc123” is more reliable than “latest campaign?”.

👤Account

1 tool

get_account_details

Retrieve your Merko account profile.

Returns name, plan, and configuration for the authenticated user.

Parameter	Type	Required	Description
No parameters required.

Example prompt

Natural Language

"Show me my Merko account details"

📣Campaigns

4 tools

get_campaigns

List campaigns, paginated, newest first.

Parameter	Type	Required	Description
page_number	string	required	Page `"1"` or higher.

get_campaign_stats

Delivery, open, bounce, spam, and reject rates for a campaign.

Parameter	Type	Required	Description
campaign_id	string	required	ID from `get_campaigns`

Returns

JSON

{
  "bounce_rate":            2.4,
  "delivery_rate":          97.1,
  "opened_rate":            34.8,
  "spam_rate":              0.1,
  "sent_rate":              99.2,
  "reject_rate":            0.5,
  "total_customers_mapped": 1500
}

create_campaign

Create a campaign with template, audience, dates.

Parameter	Type	Required	Description
name	string	required	Internal name
subject	string	required	Email subject
templateId	string	required	Template ID
startDate	string	required	Start date (ISO 8601)
endDate	string	required	End date (ISO 8601)
customerGroup	string	required	Audience group ID
mailToUse	string	required	Sender email
friendlyName	string	required	Sender display name

get_campaign_report

Full analytics report for a campaign.

Parameter	Type	Required	Description
campaign_id	string	required	Unique campaign ID

👥Audiences

3 tools

get_all_audiences

List all customer groups (audience segments).

Group IDs are used as customerGroup when creating campaigns.

Parameter	Type	Required	Description
No parameters required.

get_audience

Members of a segment, paginated.

Parameter	Type	Required	Description
group_id	string	required	Group ID
page_number	string	required	`"1"` or higher

get_list

Recipient list for a campaign with delivery status.

Parameter	Type	Required	Description
campaign_id	string	required	Campaign ID
page_number	string	required	`"1"` or higher

🗂️Profiles (Leads)

6 tools

get_profiles

List all lead profiles, paginated.

Parameter	Type	Required	Description
page_number	string	required	Page `"1"` or higher

get_profile_names

Lightweight list — name + ID only. Ideal for lookups.

Parameter	Type	Required	Description
page_number	string	required	Page number

get_profile

Full details of a single lead by ID.

Parameter	Type	Required	Description
profile_id	string	required	Unique lead ID

create_profile

Add a new lead to a group.

Parameter	Type	Required	Description
group_name	string	required	Group name
group_id	string	required	Group ID
first_name	string	required	First name
last_name	string	required	Last name
email	string	required	Email
mobile_number	string	required	Mobile
whatsapp_number	string	required	WhatsApp

update_profile

Update one or more fields. Only supply what you change.

Parameter	Type	Required	Description
profile_id	string	required	Lead ID
group_id	string	optional	Move to group
first_name	string	optional	Updated first name
last_name	string	optional	Updated last name
email	string	optional	Updated email
mobile_number	string	optional	Updated mobile
whatsapp_number	string	optional	Updated WhatsApp

delete_profile

Permanently delete a lead. Cannot be undone.

⚠️

Irreversible. Deleted profiles cannot be recovered.

Parameter	Type	Required	Description
profile_id	string	required	Lead ID to delete

🖼️Images

2 tools

upload_image_from_url

Download from URL and upload to Merko CDN. Returns hosted URL.

Detects format, obtains pre-signed URL, returns CDN URL ready for templates.

Parameter	Type	Required	Description
image_url	string	required	Public image URL (JPEG, PNG, WebP, GIF)

Returns

JSON

{
  "success":  true,
  "imageUrl": "https://cdn.merko.ai/images/abc123.png",
  "key":      "images/abc123.png"
}

upload_image_via_file

Upload base64-encoded file directly.

Use when you have raw image data rather than a URL.

Parameter	Type	Required	Description
file_base64	string	required	Base64 data
file_name	string	required	Filename e.g. `banner.png`
content_type	string	optional	MIME e.g. `image/png` — auto-detected if omitted

Returns

JSON

{
  "success":  true,
  "imageUrl": "https://cdn.merko.ai/images/xyz789.png",
  "key":      "images/xyz789.png"
}

✉️Email Templates

2 tools

create_email_template

Create a new HTML email template.

Parameter	Type	Required	Description
name	string	required	Display name
tag_name	string	required	Tag e.g. `newsletter`, `promo`
content	string	required	Full HTML body
thumbnail	string	optional	Preview thumbnail URL

get_email_template

Retrieve all templates — global Merko + your custom.

Returns two sets: shared Merko templates and your user-specific ones.

Parameter	Type	Required	Description
No parameters required.

Returns

JSON

{
  "global":       [...], // Merko shared templates
  "userSpecific": [...]  // Your custom templates
}

💬Examples

Copy these prompts into your AI assistant after connecting Merko. The assistant will call the right tool automatically.

Goal	Example prompt	Tool called
See campaigns	“List my last 3 Merko campaigns and their open rates”	get_campaigns → get_campaign_stats
Create campaign	“Create a campaign named Summer Sale, subject ‘50% off this week’, using template tpl_123 for group grp_456 starting tomorrow”	create_campaign
Manage leads	“Add lead Jane Doe jane@example.com to Newsletter group and then show me her profile”	create_profile → get_profile
Upload image	“Upload https://example.com/banner.png to Merko and give me the CDN URL”	upload_image_from_url
Template library	“Show me all Merko email templates and create a new promo template with this HTML …”	get_email_template → create_email_template

💡

Tip: Always include IDs when you have them — “stats for campaign abc123” is more reliable than “latest campaign”.

Tool call (JSON-RPC)

Example — Streamable HTTP

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_campaigns",
    "arguments": { "page_number": "1" }
  }
}

🛠️Troubleshooting

Issue	Fix
Server not found / health fails	Confirm URL is exactly `https://mcp.merko.ai/mcp`. Test `GET https://mcp.merko.ai/health` → 200 OK.
OAuth popup doesn’t open	Disable popup blocker for your AI client, or use the desktop app. The client must be able to open `/authorize`.
Authorized but no tools appear	Start a completely new chat/session — clients load tools only at session start.
401 Unauthorized	Token expired or missing. Re-authenticate: disconnect the Merko server and reconnect to trigger OAuth again.
Page number must be 1 or higher	All paginated tools expect `page_number` as string `"1"`, not number `1`.
Token expired mid-session	Client auto-refreshes via `refresh_token`. If it fails, disconnect and reconnect in Settings.
ChatGPT: tools not listed	Ensure Developer mode is on and Merko app is enabled via the + button in a new conversation.
Cursor: red dot	Check URL, ensure Type is HTTP, and re-authorize via browser.

📡Endpoints & Errors

Endpoints

POST/mcpStreamable HTTP — primary MCP endpoint

GET/healthHealth check — 200 OK

OAuth discovery via /.well-known/oauth-authorization-server, protected resource via /.well-known/oauth-protected-resource, and JWKS via /.well-known/jwks.json. Your client discovers these automatically — no manual calls needed.

Error Codes

HTTP	Error	Description
401	Unauthorized	Missing/invalid bearer token. Re-authenticate.
400	invalid_request	Missing required parameters.
400	unsupported_grant_type	`grant_type` must be `authorization_code` or `refresh_token`.
400	invalid_token	Token signature failed or expired.
500	server_error	Unexpected server error. Contact Merko support if persistent.

🚀

Merko MCP v1 — OAuth 2.0 + PKCE, Streamable HTTP, and 18 tools across Account, Campaigns, Audiences, Profiles, Images, Email Templates.