Model Context Protocol
Merko MCP Server
Connect AI assistants like Claude Desktop, Claude Code, Cursor, and ChatGPT directly to your Merko marketing account. Manage campaigns, audiences, leads, email templates, and images — without leaving your AI assistant.
ℹ️
The Merko MCP Server uses
OAuth 2.0 Dynamic Client Registration. When an
AI tool connects for the first time, it registers itself
automatically, opens your browser for login, and requests
authorization to access your account.
The Merko MCP server gives AI tools a standardized way to:
- Access account and profile information
- List, create, and analyze marketing campaigns
- Manage customer audiences and audience segments
- Create, update, and delete lead profiles
- Upload images via URL or direct file upload to Merko CDN
- Create and retrieve email templates
Prerequisites
1
A Merko account
You need an active Merko account at
app.merko.ai. Your existing login credentials are used for OAuth
authorization.
2
An MCP-compatible AI client
Claude Desktop, Claude Code, Cursor, or any client that
supports MCP with OAuth 2.0. See
Connect Claude Desktop,
Claude Code, Cursor, or
ChatGPT.
3
MCP server URL
The Merko MCP server URL is
https://mcp.merko.ai/mcp.
What You Can Do
Once connected, your AI assistant can perform actions across six functional areas:
Account
Retrieve your account details and profile information using
natural language.
Campaigns
List campaigns, view stats and analytics, and create new
campaigns with a subject, template, and audience group.
Audiences
Browse all audience groups, inspect individual segments, and
list campaign recipients.
Leads & Profiles
Full CRUD on customer profiles — get, create, update, and
delete leads with contact details.
Images
Upload images to Merko CDN by URL or base64 file. Returns a
hosted image URL ready for templates.
Email Templates
Create branded HTML email templates with name, category tag,
HTML content, and optional thumbnail.
OAuth 2.0 Authentication
The Merko MCP server uses OAuth 2.0 with PKCE (Proof Key for Code Exchange). MCP clients that support OAuth Dynamic Client Registration handle this flow automatically.
✅
Modern MCP clients handle this automatically.
Claude Desktop, Claude Code, and ChatGPT will prompt you to log
in via your browser — no manual token management needed.
How it works
1
Client Registration
The AI client calls
POST /register to register
itself. The server returns a client_id and
redirect URI.
2
Authorization
The client redirects you to
GET /authorize,
which forwards to Merko's secure hosted login page. You log
in with your Merko credentials and approve access.
3
Token Exchange
After approval, the client exchanges the authorization code
at
POST /token using PKCE — no client secret
needed. You receive an access token and refresh token.
4
Authenticated MCP Calls
The client sends
Authorization: Bearer <token> with every
request to /mcp.
ℹ️
Clients discover the OAuth endpoints automatically from
/.well-known/oauth-authorization-server. There is
no manual client registration, no client secret, and no token
handling required on your side — tokens are refreshed
automatically by your MCP client.
HTTP Transport
Streamable HTTP is the transport used by all modern MCP clients.
POST/mcpStreamable HTTP — primary MCP endpoint
ℹ️
Every request to
/mcp must include a valid bearer
token in the Authorization header. The server
validates it before processing any tool calls.
HTTP Request
POST /mcp HTTP/1.1 Host: mcp.merko.ai Authorization: Bearer <access_token> Content-Type: application/json
Connect Claude Desktop
Add the Merko MCP server to Claude Desktop by editing its configuration file.
1
Open Claude Desktop settings
Go to
Claude → Click the '+' button under the chatbox →
Connectors → Add Custom Connectors.
2
Add the Merko MCP server entry
Add https://mcp.merko.ai/mcp in the MCP URL
field
3
Authorize via browser
Claude Desktop will open your browser and prompt you to log
in to Merko. Approve access to complete the connection.
Connect Claude Code
Register the Merko MCP server with one terminal command:
Shell
claude mcp add --transport http merko https://mcp.merko.ai/mcp
Or add it to .mcp.json at the root of your project to
share the config with your team:
.mcp.json
{
"mcpServers": {
"Merko": {
"type": "http",
"url": "https://mcp.merko.ai/mcp"
}
}
}
💡
Run
claude mcp list to confirm the server is
registered. Start a new Claude Code session to begin using Merko
tools.
Connect Cursor
Cursor supports MCP servers natively. Add Merko via the Settings panel or your project config file.
1
Open Cursor Settings
Go to Cursor → Settings → MCP (or press
Cmd/Ctrl + Shift + J and search for "MCP").
2
Add a new MCP server
Click + Add new MCP server, select
Type: HTTP, and paste your Merko MCP URL.
MCP Server URL
https://mcp.merko.ai/mcp
Alternatively, add it to .cursor/mcp.json in your
project root:
.cursor/mcp.json
{
"mcpServers": {
"Merko": {
"type": "http",
"url": "https://mcp.merko.ai/mcp"
}
}
}
3
Authorize via browser
Cursor will open your browser to log in to Merko. Approve
access to complete the OAuth flow.
4
Start using Merko tools
Open a new Cursor chat session. Try:
"List my Merko campaigns" or
"Upload this image to Merko CDN."
💡
Cursor shows a green dot next to connected MCP servers. If the
dot is red, check your URL and try reconnecting.
Connect ChatGPT
ChatGPT supports MCP servers through ChatGPT Apps, available on Plus, Team, and Enterprise plans. Once connected, you can manage Merko campaigns, leads, and templates through natural language.
⚠️
Use the Apps page to add a custom app. Check
help.openai.com
to confirm availability on your plan.
1
Open ChatGPT Apps
Go to Settings → Apps in the ChatGPT web
app.
2
Enable developer mode
Open Advanced settings and turn on
Developer mode so you can create a custom
app.
3
Create a new app
Click Create App, enter the Merko MCP
server URL, and choose
OAuth authentication.
4
Connect and authorize
After creating the app, connect it and log in through the
browser prompt to grant Merko access.
5
Start a new conversation
Open a new chat, then enable the Merko app from the
+ button below the chat box. Try:
"Show me my Merko campaigns" or
"Create a lead named Jane Doe in my Newsletter
group."
💡
Tip: Include IDs when you have them.
"Get stats for campaign ID abc123" is more reliable
than "How is my latest campaign?"
Troubleshooting
| Issue | Fix |
|---|---|
| Server not found |
Confirm the MCP URL is correct and the server is running.
Test that /health returns 200.
|
| OAuth popup does not open | Disable popup blockers for ChatGPT, or switch to the desktop app. |
| Authorized but no tools appear | Start a completely new conversation — ChatGPT loads tools at session start only. |
| Token expired mid-session | ChatGPT auto-refreshes tokens. If it fails, disconnect and reconnect in Settings. |
Account Tools
1 tool
get_account_details
Retrieve your Merko account details and profile information.
Returns the full account profile associated with the authenticated user, including name, plan, and configuration details.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| No parameters required. | |||
Example prompt
Natural Language
"Show me my Merko account details"
Campaign Tools
4 tools
get_campaigns
List all marketing campaigns for your account, paginated,
ordered newest first.
| Parameter | Type | Required | Description |
|---|---|---|---|
| page_number | string | required |
Page to retrieve. Must be "1" or higher.
|
get_campaign_stats
Get delivery, open, bounce, spam, and reject rate statistics
for a campaign.
| Parameter | Type | Required | Description |
|---|---|---|---|
| campaign_id | string | required |
Unique campaign identifier (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 new marketing campaign with a template, audience
group, and scheduled dates.
| Parameter | Type | Required | Description |
|---|---|---|---|
| name | string | required | Internal campaign name |
| subject | string | required | Email subject line shown to recipients |
| templateId | string | required | ID of the email template to use |
| startDate | string | required | Campaign start date (ISO 8601) |
| endDate | string | required | Campaign end date (ISO 8601) |
| customerGroup | string | required | Audience group ID to target |
| mailToUse | string | required | Sender email address |
| friendlyName | string | required | Display name shown as the email sender |
get_campaign_report
Get the full analytics report for a specific campaign.
| Parameter | Type | Required | Description |
|---|---|---|---|
| campaign_id | string | required | Unique campaign identifier |
Audience Tools
3 tools
get_all_audiences
Retrieve all customer group lists (audience segments) in
your account.
Returns all customer groups. Group IDs are used as the
customerGroup parameter when creating campaigns.
| Parameter | Type | Required | Description |
|---|---|---|---|
| No parameters required. | |||
get_audience
Retrieve members of a specific audience segment, paginated.
| Parameter | Type | Required | Description |
|---|---|---|---|
| group_id | string | required | Customer group identifier |
| page_number | string | required |
Page number ("1" or higher)
|
get_list
Get the recipient list for a specific campaign with
per-recipient delivery status.
| Parameter | Type | Required | Description |
|---|---|---|---|
| campaign_id | string | required | Unique campaign identifier |
| page_number | string | required |
Page number ("1" or higher)
|
Profile (Lead) Tools
6 tools
get_profiles
List all lead profiles in your account with full details,
paginated.
| Parameter | Type | Required | Description |
|---|---|---|---|
| page_number | string | required |
Page number ("1" or higher)
|
get_profile_names
Lightweight lead list — returns only name and ID. Ideal for
lookups before update or delete.
| Parameter | Type | Required | Description |
|---|---|---|---|
| page_number | string | required |
Page number ("1" or higher)
|
get_profile
Retrieve full details of a single lead by their profile ID.
| Parameter | Type | Required | Description |
|---|---|---|---|
| profile_id | string | required | Unique lead profile identifier |
create_profile
Add a new lead to a customer group with full contact
details.
| Parameter | Type | Required | Description |
|---|---|---|---|
| group_name | string | required | Name of the lead group |
| group_id | string | required | ID of the lead group |
| first_name | string | required | Lead's first name |
| last_name | string | required | Lead's last name |
| string | required | Lead's email address | |
| mobile_number | string | required | Lead's mobile phone number |
| whatsapp_number | string | required | Lead's WhatsApp number |
update_profile
Update one or more fields on an existing lead. Only supply
the fields you want to change.
| Parameter | Type | Required | Description |
|---|---|---|---|
| profile_id | string | required | Unique lead profile identifier |
| group_id | string | optional | Move lead to a different group |
| first_name | string | optional | Updated first name |
| last_name | string | optional | Updated last name |
| string | optional | Updated email address | |
| mobile_number | string | optional | Updated mobile number |
| whatsapp_number | string | optional | Updated WhatsApp number |
delete_profile
Permanently delete a lead profile. This action cannot be
undone.
⚠️
Irreversible. Deleted profiles cannot be
recovered.
| Parameter | Type | Required | Description |
|---|---|---|---|
| profile_id | string | required | Unique lead profile identifier to delete |
Image Tools
2 tools
upload_image_from_url
Download an image from a public URL and upload it to Merko's
CDN. Returns a hosted image URL.
The server downloads the image, detects its format, obtains a pre-signed S3 URL, and returns a CDN-hosted URL ready for use in templates or campaigns.
| Parameter | Type | Required | Description |
|---|---|---|---|
| image_url | string | required | Publicly accessible image URL (JPEG, PNG, WebP, GIF) |
Returns
JSON
{
"success": true,
"imageUrl": "https://cdn.merko.com/images/abc123.png",
"key": "images/abc123.png"
}
upload_image_via_file
Upload an image directly from a base64-encoded file payload.
Use when you have raw image data rather than a URL. Only image MIME types are accepted.
| Parameter | Type | Required | Description |
|---|---|---|---|
| file_base64 | string | required | Base64-encoded image data |
| file_name | string | required |
Filename with extension (e.g. banner.png)
|
| content_type | string | optional |
MIME type (e.g. image/png). Auto-detected
from filename if omitted.
|
Returns
JSON
{
"success": true,
"imageUrl": "https://cdn.merko.com/images/xyz789.png",
"key": "images/xyz789.png"
}
Email Template Tools
2 tools
create_email_template
Create a new HTML email template stored in your Merko
account.
| Parameter | Type | Required | Description |
|---|---|---|---|
| name | string | required | Display name for the template |
| tag_name | string | required |
Category tag (e.g. newsletter,
promo, transactional)
|
| content | string | required | Full HTML body of the email template |
| thumbnail | string | optional | URL of a preview thumbnail for the template gallery |
get_email_template
Retrieve all available email templates — global Merko
templates and your custom ones.
Returns two sets: global templates shared across all Merko accounts, and user-specific templates you've created.
| Parameter | Type | Required | Description |
|---|---|---|---|
| No parameters required. | |||
Returns
JSON
{
"global": [...], // Merko shared templates
"userSpecific": [...] // Your custom templates
}
All Endpoints
MCP Transport
POST/mcpStreamable HTTP transport
OAuth
OAuth endpoints (/register, /authorize,
/token, /callback) are used
automatically by your MCP client and discovered via
/.well-known/oauth-authorization-server. You never
need to call them directly.
Utility
GET/healthServer health check — returns 200 OK
Error Codes
| HTTP Status | Error | Description |
|---|---|---|
| 401 | Unauthorized | Missing or invalid bearer token. Re-authenticate the client. |
| 400 | invalid_request | Missing required parameters in the request body or query string. |
| 400 | unsupported_grant_type |
grant_type must be
authorization_code or
refresh_token.
|
| 400 | invalid_token | Token signature verification failed or the token has expired. |
| 500 | server_error | Unexpected server error. Contact Merko support if this persists. |
| Tool | Missing Authorization token | MCP tool called without a valid session. Re-authenticate. |
| Tool | Page number must be 1 or higher |
Paginated tools require page_number as a string
"1" or greater.
|
Changelog
🚀
Initial Release
Launched Merko MCP Server with OAuth 2.0 + PKCE, Streamable HTTP transport, and 18 tools across Account, Campaigns, Audiences, Profiles, Images, and Email Templates.
Launched Merko MCP Server with OAuth 2.0 + PKCE, Streamable HTTP transport, and 18 tools across Account, Campaigns, Audiences, Profiles, Images, and Email Templates.