# marketo-mcp-server

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

A Model Context Protocol server for Marketo — give Claude and other AI assistants direct access to your Marketo instance.

Query leads, inspect programs, review emails and forms, manage static and smart lists, explore channels and landing pages, and kick off bulk exports — all through natural language.

---

## Features

| Category | What you can do |
|---|---|
| **Leads** | Get by ID or email, create/update in batch, delete, retrieve activity log |
| **Programs** | List, get by ID, clone, get members |
| **Emails** | List, get by ID, clone, send sample/test |
| **Forms** | List, get by ID, clone, approve |
| **Smart Lists** | List, get by ID with full filter definitions |
| **Static Lists** | Get members, add leads, remove leads |
| **Channels** | List, get by ID, create with progression statuses |
| **Landing Pages** | List, get by ID, clone |
| **Bulk Export** | Create job, enqueue, poll status, download file |

---

## Prerequisites

- Node.js 20+
- A Marketo instance with REST API access
- A Marketo API-only user and LaunchPoint service with **Client ID** and **Client Secret**

---

## Setup

### 1. Get your Marketo REST credentials

In Marketo Admin: **Integration → LaunchPoint** → create or select a service → copy Client ID and Secret. Your base URL is under **Integration → Web Services** (e.g. `https://xxx-xxx-xxx.mktorest.com`).

### 2. Set environment variables

```bash
MARKETO_CLIENT_ID=your_client_id
MARKETO_CLIENT_SECRET=your_client_secret
MARKETO_BASE_URL=https://xxx-xxx-xxx.mktorest.com
```

---

## Usage

### Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "marketo": {
      "command": "npx",
      "args": ["marketo-mcp-server"],
      "env": {
        "MARKETO_CLIENT_ID": "your_client_id",
        "MARKETO_CLIENT_SECRET": "your_client_secret",
        "MARKETO_BASE_URL": "https://xxx-xxx-xxx.mktorest.com"
      }
    }
  }
}
```

### Claude Code

```bash
claude mcp add marketo-mcp-server npx marketo-mcp-server \
  -e MARKETO_CLIENT_ID=your_client_id \
  -e MARKETO_CLIENT_SECRET=your_client_secret \
  -e MARKETO_BASE_URL=https://xxx-xxx-xxx.mktorest.com
```

### Cursor

Add to `.cursor/mcp.json` in your project root (or `~/.cursor/mcp.json` globally):

```json
{
  "mcpServers": {
    "marketo": {
      "command": "npx",
      "args": ["marketo-mcp-server"],
      "env": {
        "MARKETO_CLIENT_ID": "your_client_id",
        "MARKETO_CLIENT_SECRET": "your_client_secret",
        "MARKETO_BASE_URL": "https://xxx-xxx-xxx.mktorest.com"
      }
    }
  }
}
```

### Docker

```bash
docker build -t marketo-mcp-server .
docker run -e MARKETO_CLIENT_ID=... -e MARKETO_CLIENT_SECRET=... -e MARKETO_BASE_URL=... marketo-mcp-server
```

---

## Tools reference

### Leads (5 tools)

| Tool | Description |
|---|---|
| `marketo_get_lead_by_id` | Get a single lead by Marketo lead ID |
| `marketo_get_lead_by_email` | Look up a lead by email address |
| `marketo_create_or_update_leads` | Batch upsert up to 300 leads |
| `marketo_delete_lead` | Permanently delete a lead by ID |
| `marketo_get_lead_activities` | Get activity log for a lead (filterable by activity type) |

### Programs (4 tools)

| Tool | Description |
|---|---|
| `marketo_get_programs` | List programs with pagination and type/date filtering |
| `marketo_get_program_by_id` | Get full program metadata by ID |
| `marketo_clone_program` | Clone a program with all local assets into a target folder |
| `marketo_get_program_members` | Get leads enrolled in a program |

### Emails (4 tools)

| Tool | Description |
|---|---|
| `marketo_get_emails` | List email assets with status filtering |
| `marketo_get_email_by_id` | Get full email metadata including HTML and module structure |
| `marketo_clone_email` | Clone an email asset to a target folder |
| `marketo_send_sample` | Send a test/sample email, optionally rendered with a lead's tokens |

### Forms (4 tools)

| Tool | Description |
|---|---|
| `marketo_get_forms` | List forms with pagination and status filtering |
| `marketo_get_form_by_id` | Get form metadata including fields and visibility rules |
| `marketo_clone_form` | Clone a form to a target folder |
| `marketo_approve_form` | Approve a form draft to make it live |

### Smart Lists (2 tools)

| Tool | Description |
|---|---|
| `marketo_get_smart_lists` | List smart lists with pagination |
| `marketo_get_smart_list_by_id` | Get a smart list with its full filter definitions |

### Static Lists (3 tools)

| Tool | Description |
|---|---|
| `marketo_get_lead_lists` | Get leads that are members of a static list |
| `marketo_add_leads_to_list` | Add up to 300 leads to a static list |
| `marketo_remove_leads_from_list` | Remove up to 300 leads from a static list |

### Channels (3 tools)

| Tool | Description |
|---|---|
| `marketo_get_channels` | List all channels and their progression statuses |
| `marketo_get_channel_by_id` | Get a single channel by ID |
| `marketo_create_channel` | Create a channel with custom progression statuses |

### Landing Pages (3 tools)

| Tool | Description |
|---|---|
| `marketo_get_landing_pages` | List landing pages with status filtering |
| `marketo_get_landing_page_by_id` | Get full LP metadata including template and form embeds |
| `marketo_clone_landing_page` | Clone a landing page to a target folder |

### Bulk Export (4 tools)

| Tool | Description |
|---|---|
| `marketo_create_bulk_export_leads` | Create a bulk lead export job with field list and date filter |
| `marketo_enqueue_bulk_export` | Enqueue a created export job for processing |
| `marketo_get_bulk_export_status` | Poll the status of a running export job |
| `marketo_get_bulk_export_file` | Download the file from a completed export job |

---

## Example prompts

- "Show me all leads created this week from the Webinar source"
- "What programs are currently active and what channel is each one under?"
- "Find all forms on the Contact Us landing page and show me their fields"
- "Clone the Q1 Webinar program into the Q2 folder and name it Q2 Webinar"
- "Export all leads updated in the last 30 days to CSV — email, firstName, lastName, company"
- "Send a sample of email ID 1234 to test@example.com rendered with lead 5678's data"

---

## Authentication

Marketo uses OAuth 2.0 client credentials. The server obtains and caches a token automatically, refreshing it 60 seconds before expiry. No manual token management required.

---

## License

MIT — see [LICENSE](LICENSE).