Keila MCP

MCP server for Keila — gives any MCP-compatible AI assistant full control over your Keila email campaigns, contacts, segments and forms.

Note

Migrating from an earlier clone? The source directory was renamed from repo/ to keila-mcp/. Update any paths in your MCP client config accordingly.

Two ways to use keila-mcp

	Option A — `uvx` ✅ recommended	Option B — Local install
What it does	Downloads and runs keila-mcp automatically from PyPI	You clone the repo and manage the install yourself
Requires	`uv`	Python 3.10+, git
Updates	Automatic — always runs the latest version	Manual — `git pull` + `pip install .`
Best for	Most users	Offline use, development, contributors

Requirements

A running Keila instance — self-host with Docker or use Keila Cloud
A Keila API key — Settings → API Keys → Create

Option A — uvx (recommended)

Important

You need uv installed first. If you don't have it:

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Then restart your terminal.

No cloning, no virtualenv, no pip install. Just add the config to your MCP client — uvx downloads and caches keila-mcp automatically on first run.

Skip straight to Client Configuration and use the Option A config for your client.

Option B — Local install

Use this for offline access, to modify the code, or to contribute.

Python 3.10+, git

macOS / Linux

git clone https://github.com/punkyard/keila-mcp.git keila-mcp
cd keila-mcp
python -m venv .venv
source .venv/bin/activate
pip install .
pwd

Copy the path printed by pwd — you will need it in the Option B configs below.

Windows

git clone https://github.com/punkyard/keila-mcp.git keila-mcp
cd keila-mcp
python -m venv .venv
.venv\Scripts\activate
pip install .
cd

Copy the path printed by cd — you will need it in the Option B configs below.

Client Configuration

Set these environment variables in your MCP client config:

Variable	Value
`KEILA_URL`	Your Keila instance URL, e.g. `https://keila.mydomain.com`
`KEILA_API_KEY`	Your Keila API key — Settings → API Keys → Create
`KEILA_MCP_HTTP_PORT`	(optional) HTTP port for the MCP server. Default: `3001`

Each client below shows Option A (uvx) and Option B (local install) — pick yours.

Important

Option B users: replace /path/to/keila-mcp with the path printed by pwd (or cd on Windows) from the install step above.

Claude Desktop

File (macOS): ~/Library/Application Support/Claude/claude_desktop_config.json
File (Windows): %APPDATA%\Claude\claude_desktop_config.json

Option A — uvx:

{
  "mcpServers": {
    "keila": {
      "command": "uvx",
      "args": ["keila-mcp"],
      "env": {
        "KEILA_URL": "https://your-keila-instance.com",
        "KEILA_API_KEY": "your-api-key"
      }
    }
  }
}

Option B — Local install:

{
  "mcpServers": {
    "keila": {
      "command": "/path/to/keila-mcp/.venv/bin/python",
      "args": ["-m", "keila_mcp.mcp_server"],
      "env": {
        "KEILA_URL": "https://your-keila-instance.com",
        "KEILA_API_KEY": "your-api-key"
      }
    }
  }
}

Fully quit and relaunch Claude Desktop after saving.

Claude Code

Option A — uvx:

claude mcp add-json keila '{
  "type": "stdio",
  "command": "uvx",
  "args": ["keila-mcp"],
  "env": {
    "KEILA_URL": "https://your-keila-instance.com",
    "KEILA_API_KEY": "your-api-key"
  }
}'

Option B — Local install:

claude mcp add-json keila '{
  "type": "stdio",
  "command": "/path/to/keila-mcp/.venv/bin/python",
  "args": ["-m", "keila_mcp.mcp_server"],
  "env": {
    "KEILA_URL": "https://your-keila-instance.com",
    "KEILA_API_KEY": "your-api-key"
  }
}'

Add --scope global to make it available in all projects.

Cursor · Cline / Roo Code · Windsurf · OpenClaw

Cursor: .cursor/mcp.json in your project, or ~/.cursor/mcp.json for global
Cline / Roo Code: MCP Servers config via the sidebar
Windsurf: ~/.codeium/windsurf/mcp_config.json
OpenClaw: ~/.openclaw/mcp.json

Option A — uvx:

{
  "mcpServers": {
    "keila": {
      "command": "uvx",
      "args": ["keila-mcp"],
      "env": {
        "KEILA_URL": "https://your-keila-instance.com",
        "KEILA_API_KEY": "your-api-key"
      }
    }
  }
}

Option B — Local install:

{
  "mcpServers": {
    "keila": {
      "command": "/path/to/keila-mcp/.venv/bin/python",
      "args": ["-m", "keila_mcp.mcp_server"],
      "env": {
        "KEILA_URL": "https://your-keila-instance.com",
        "KEILA_API_KEY": "your-api-key"
      }
    }
  }
}

VS Code (GitHub Copilot Agent Mode)

Create .vscode/mcp.json in your project:

Option A — uvx:

{
  "servers": {
    "keila": {
      "command": "uvx",
      "args": ["keila-mcp"],
      "env": {
        "KEILA_URL": "https://your-keila-instance.com",
        "KEILA_API_KEY": "${input:keilaApiKey}"
      }
    }
  },
  "inputs": [
    {
      "id": "keilaApiKey",
      "type": "promptString",
      "description": "Keila API Key",
      "password": true
    }
  ]
}

Option B — Local install:

{
  "servers": {
    "keila": {
      "command": "/path/to/keila-mcp/.venv/bin/python",
      "args": ["-m", "keila_mcp.mcp_server"],
      "env": {
        "KEILA_URL": "https://your-keila-instance.com",
        "KEILA_API_KEY": "${input:keilaApiKey}"
      }
    }
  },
  "inputs": [
    {
      "id": "keilaApiKey",
      "type": "promptString",
      "description": "Keila API Key",
      "password": true
    }
  ]
}

Requires Copilot Chat in Agent mode. VS Code will prompt for the API key on first use.

Zed

In ~/.config/zed/settings.json (global) or .zed/settings.json (project):

Option A — uvx:

{
  "context_servers": {
    "keila": {
      "command": {
        "path": "uvx",
        "args": ["keila-mcp"],
        "env": {
          "KEILA_URL": "https://your-keila-instance.com",
          "KEILA_API_KEY": "your-api-key"
        }
      }
    }
  }
}

Option B — Local install:

{
  "context_servers": {
    "keila": {
      "command": {
        "path": "/path/to/keila-mcp/.venv/bin/python",
        "args": ["-m", "keila_mcp.mcp_server"],
        "env": {
          "KEILA_URL": "https://your-keila-instance.com",
          "KEILA_API_KEY": "your-api-key"
        }
      }
    }
  }
}

OpenCode

In ~/.config/opencode/opencode.json (global) or opencode.json (project):

Option A — uvx:

{
  "mcp": {
    "keila": {
      "type": "local",
      "command": ["uvx", "keila-mcp"],
      "env": {
        "KEILA_URL": "https://your-keila-instance.com",
        "KEILA_API_KEY": "your-api-key"
      }
    }
  }
}

Option B — Local install:

{
  "mcp": {
    "keila": {
      "type": "local",
      "command": ["/path/to/keila-mcp/.venv/bin/python", "-m", "keila_mcp.mcp_server"],
      "env": {
        "KEILA_URL": "https://your-keila-instance.com",
        "KEILA_API_KEY": "your-api-key"
      }
    }
  }
}

Pi Agent

In ~/.pi/agent/mcp.json:

Option A — uvx:

{
  "keila": {
    "command": "uvx",
    "args": ["keila-mcp"],
    "env": {
      "KEILA_URL": "https://your-keila-instance.com",
      "KEILA_API_KEY": "your-api-key"
    },
    "lifecycle": "on-demand"
  }
}

Option B — Local install:

{
  "keila": {
    "command": "/path/to/keila-mcp/.venv/bin/python",
    "args": ["-m", "keila_mcp.mcp_server"],
    "env": {
      "KEILA_URL": "https://your-keila-instance.com",
      "KEILA_API_KEY": "your-api-key"
    },
    "lifecycle": "on-demand"
  }
}

Hermes

In ~/.hermes/config.yaml:

Option A — uvx:

mcp_servers:
  keila:
    command: uvx
    args:
      - keila-mcp
    env:
      KEILA_URL: https://your-keila-instance.com
      KEILA_API_KEY: your-api-key

Option B — Local install:

mcp_servers:
  keila:
    command: /path/to/keila-mcp/.venv/bin/python
    args:
      - -m
      - keila_mcp.mcp_server
    env:
      KEILA_URL: https://your-keila-instance.com
      KEILA_API_KEY: your-api-key

OpenAI Codex CLI

File: ~/.codex/config.toml (global) or .codex/config.toml (project):

Option A — uvx:

[mcp_servers.keila]
command = "uvx"
args = ["keila-mcp"]

[mcp_servers.keila.env]
KEILA_URL = "https://your-keila-instance.com"
KEILA_API_KEY = "your-api-key"

Option B — Local install:

[mcp_servers.keila]
command = "/path/to/keila-mcp/.venv/bin/python"
args = ["-m", "keila_mcp.mcp_server"]

[mcp_servers.keila.env]
KEILA_URL = "https://your-keila-instance.com"
KEILA_API_KEY = "your-api-key"

Running manually (for testing)

# Option A — uvx
uvx keila-mcp

# Option B — local install, stdio mode (default)
python -m keila_mcp.mcp_server

# Option B — local install, HTTP mode
python -m keila_mcp.mcp_server --http
# optional: export KEILA_MCP_HTTP_PORT=8325

Tools

Tool	Description
`list_campaigns`	List all campaigns with optional status/search filter
`create_campaign`	Create a new campaign
`get_campaign`	Get a campaign by ID
`update_campaign`	Update an existing campaign
`delete_campaign`	Delete a campaign
`send_campaign`	Send a campaign immediately
`schedule_campaign`	Schedule a campaign for later delivery
`create_contact`	Create a new contact
`get_contact`	Get a contact by ID
`update_contact`	Update a contact
`delete_contact`	Delete a contact
`list_contacts`	List contacts with optional filtering
`update_contact_data`	Merge custom data fields on a contact
`replace_contact_data`	Replace all custom data fields on a contact
`list_senders`	List all senders
`create_segment`	Create a new segment
`list_segments`	List all segments
`get_segment`	Get a segment by ID
`update_segment`	Update a segment
`delete_segment`	Delete a segment
`list_forms`	List all forms
`get_form`	Get a form by ID
`create_form`	Create a new signup form
`update_form`	Update a form
`delete_form`	Delete a form
`submit_form`	Submit a signup form on behalf of a contact

Campaigns

`list_campaigns`

List all email campaigns with optional filtering.

Param	Type	Required	Description
`status`	string	No	Filter by: draft/scheduled/sent/archived/paused
`q`	string	No	Search by subject (case-insensitive substring)

`create_campaign`

Create a new email campaign.

Param	Type	Required	Description
`subject`	string	Yes	Campaign subject line
`body_type`	string	Yes	Body type: markdown/text/block/mjml
`text_body`	string	No	Plain text body
`preview_text`	string	No	Preview text for inbox
`sender_id`	string	No	Sender identity ID
`segment_id`	string	No	Target segment ID
`data`	object	No	Liquid template variables
`do_not_track`	boolean	No	Disable open/click tracking

`get_campaign`

Get a single campaign by ID.

Param	Type	Required	Description
`id`	string	Yes	Campaign ID

`update_campaign`

Update an existing campaign.

Param	Type	Required	Description
`id`	string	Yes	Campaign ID
`subject`	string	No	New subject line
`preview_text`	string	No	New preview text

`delete_campaign`

Delete a campaign.

Param	Type	Required	Description
`id`	string	Yes	Campaign ID

`send_campaign`

Send a campaign immediately.

Param	Type	Required	Description
`id`	string	Yes	Campaign ID
`sender_id`	string	No	Override sender identity

`schedule_campaign`

Schedule a campaign for later delivery.

Param	Type	Required	Description
`id`	string	Yes	Campaign ID
`scheduled_for`	string	Yes	ISO 8601 datetime (e.g. 2026-06-01T09:00:00Z)

Contacts

`create_contact`

Create a new contact.

Param	Type	Required	Description
`email`	string	Yes	Email address
`first_name`	string	No	First name
`last_name`	string	No	Last name
`external_id`	string	No	External system ID
`status`	string	No	Status: active/inactive/bouncing/blocked/spam
`data`	object	No	Custom fields

`get_contact`

Get a contact by ID, email, or external ID.

Param	Type	Required	Description
`id`	string	Yes	Contact identifier
`id_type`	string	No	Lookup type: id (default)/email/external_id

`update_contact`

Update an existing contact.

Param	Type	Required	Description
`id`	string	Yes	Contact identifier
`email`	string	No	New email
`first_name`	string	No	New first name
`last_name`	string	No	New last name
`external_id`	string	No	New external ID
`data`	object	No	New custom fields
`id_type`	string	No	Lookup type: id (default)/email/external_id

`delete_contact`

Delete a contact.

Param	Type	Required	Description
`id`	string	Yes	Contact identifier
`id_type`	string	No	Lookup type: id (default)/email/external_id

`list_contacts`

List contacts with pagination and optional search.

Param	Type	Required	Description
`page`	integer	No	Page number (default: 0)
`page_size`	integer	No	Results per page (default: 50)
`q`	string	No	Search query

Senders

`list_senders`

List all sender identities.

No parameters.

Contact Data

Custom data is a free-form JSON object attached to each contact. Use it to store any extra fields (e.g. plan, score, tags). Fields can be used as merge tags in campaigns via {{ contact.data.my_field }} and as segment filters. See Keila — Segments and Custom Data and Contacts API docs.

`update_contact_data`

Merge new key/value pairs into a contact's custom data field. Keys not present in data are preserved.

Param	Type	Required	Description
`id`	string	Yes	Contact ID (or email/external_id when `id_type` set)
`data`	object	Yes	Key/value pairs to merge
`id_type`	string	No	`id` (default), `email`, or `external_id`

`replace_contact_data`

Replace a contact's entire custom data field with the provided dict.

Param	Type	Required	Description
`id`	string	Yes	Contact ID (or email/external_id when `id_type` set)
`data`	object	Yes	New data dict (replaces existing)
`id_type`	string	No	`id` (default), `email`, or `external_id`

Segments

`create_segment`

Create a contact segment with a filter.

Param	Type	Required	Description
`name`	string	Yes	Segment name
`filter`	object	Yes	Keila filter expression

`list_segments`

List all segments.

No parameters.

`get_segment`

Get a segment by ID.

Param	Type	Required	Description
`id`	string	Yes	Segment ID

`delete_segment`

Delete a segment.

Param	Type	Required	Description
`id`	string	Yes	Segment ID

`update_segment`

Update a segment's name and/or filter. At least one of name or filter must be provided.

Param	Type	Required	Description
`id`	string	Yes	Segment ID
`name`	string	No	New segment name
`filter`	object	No	New filter expression

Forms

`list_forms`

List all subscription forms.

No parameters.

`get_form`

Get a form by ID.

Param	Type	Required	Description
`id`	string	Yes	Form ID

`create_form`

Create a new subscription form.

Param	Type	Required	Description
`name`	string	Yes	Form name
`sender_id`	string	No	Sender identity ID
`fields`	array	No	Form field definitions
`settings`	object	No	Form settings (double opt-in, redirect URLs, etc.)

`delete_form`

Delete a form.

Param	Type	Required	Description
`id`	string	Yes	Form ID

`update_form`

Update an existing signup form.

Param	Type	Required	Description
`id`	string	Yes	Form ID
`name`	string	No	New form name
`sender_id`	string	No	New sender identity ID
`fields`	array	No	Replacement field definitions
`settings`	object	No	Updated form settings

`submit_form`

Submit a signup form on behalf of a contact. Returns the created/updated contact on success, or {"data": {"double_opt_in_required": true}} if the form has double opt-in enabled.

Param	Type	Required	Description
`form_id`	string	Yes	Form ID
`email`	string	Yes	Contact email address
`first_name`	string	No	Contact first name
`last_name`	string	No	Contact last name
`external_id`	string	No	External identifier
`status`	string	No	Contact status (e.g. `active`)
`data`	object	No	Custom data key/value pairs

Development

pip install -e ".[dev]"
pytest tests/ -v

made with ⏳ by punkyard

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
docs/img		docs/img
keila_mcp		keila_mcp
tests		tests
.env.example		.env.example
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
pyproject.toml		pyproject.toml
uv.lock		uv.lock

Latest commit

History

Folders and files

Repository files navigation

Keila MCP

Two ways to use keila-mcp

Requirements

Option A — uvx (recommended)

Option B — Local install

macOS / Linux

Windows

Client Configuration

Claude Desktop

Claude Code

Cursor · Cline / Roo Code · Windsurf · OpenClaw

VS Code (GitHub Copilot Agent Mode)

Zed

OpenCode

Pi Agent

Hermes

OpenAI Codex CLI

Running manually (for testing)

Tools

Campaigns

list_campaigns

create_campaign

get_campaign

update_campaign

delete_campaign

send_campaign

schedule_campaign

Contacts

create_contact

get_contact

update_contact

delete_contact

list_contacts

Senders

list_senders

Contact Data

update_contact_data

replace_contact_data

Segments

create_segment

list_segments

get_segment

delete_segment

update_segment

Forms

list_forms

get_form

create_form

delete_form

update_form

submit_form

Development

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

`list_campaigns`

`create_campaign`

`get_campaign`

`update_campaign`

`delete_campaign`

`send_campaign`

`schedule_campaign`

`create_contact`

`get_contact`

`update_contact`

`delete_contact`

`list_contacts`

`list_senders`

`update_contact_data`

`replace_contact_data`

`create_segment`

`list_segments`

`get_segment`

`delete_segment`

`update_segment`

`list_forms`

`get_form`

`create_form`

`delete_form`

`update_form`

`submit_form`