{"id":37969064,"url":"https://github.com/iterable/mcp-server","last_synced_at":"2026-04-15T01:00:58.716Z","repository":{"id":325038656,"uuid":"1080796158","full_name":"Iterable/mcp-server","owner":"Iterable","description":"Iterable MCP Server","archived":false,"fork":false,"pushed_at":"2026-03-25T21:31:27.000Z","size":7439,"stargazers_count":4,"open_issues_count":1,"forks_count":3,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-26T00:33:26.078Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://iterable.github.io/mcp-server/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Iterable.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-21T22:03:52.000Z","updated_at":"2026-03-25T21:31:31.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Iterable/mcp-server","commit_stats":null,"previous_names":["iterable/mcp-server"],"tags_count":16,"template":false,"template_full_name":null,"purl":"pkg:github/Iterable/mcp-server","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Iterable%2Fmcp-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Iterable%2Fmcp-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Iterable%2Fmcp-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Iterable%2Fmcp-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Iterable","download_url":"https://codeload.github.com/Iterable/mcp-server/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Iterable%2Fmcp-server/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31821685,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-14T18:05:02.291Z","status":"ssl_error","status_checked_at":"2026-04-14T18:05:01.765Z","response_time":153,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-16T18:21:04.510Z","updated_at":"2026-04-15T01:00:58.707Z","avatar_url":"https://github.com/Iterable.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Iterable MCP Server\n\n[![npm version](https://img.shields.io/npm/v/@iterable/mcp.svg)](https://www.npmjs.com/package/@iterable/mcp)\n\n![Iterable MCP Server](images/iterable-mcp-server.png)\n\nTalk to your Iterable data using natural language. Ask questions or give instructions like *\"How many campaigns did we send last week?\"*, *\"Show me my most recent templates\"*, or *\"Build me a beautiful email template that does the following...\"* and get instant answers without writing code or navigating dashboards.\n\n**Supported AI clients:**\n- [Cursor](https://cursor.com/)\n- [Claude Desktop](https://www.claude.com/download)\n- [Claude Code](https://github.com/anthropics/claude-code)\n- [Gemini CLI](https://github.com/google-gemini/gemini-cli)\n- [Windsurf](https://windsurf.com/)\n- [Antigravity by Google](https://antigravity.google/)\n\n## What is MCP?\n\n[Model Context Protocol (MCP)](https://modelcontextprotocol.io/) is an open standard that lets AI assistants securely connect to external tools and APIs. This server acts as a bridge between your AI client and Iterable, translating natural language requests into safe API calls.\n\n## Installation\n\n**Prerequisites:**\n- Node.js \u003e= 20 (v22 LTS recommended)\n- An Iterable API key\n\n```bash\nnpx @iterable/mcp setup\n```\n\n![Iterable MCP Server Setup](images/iterable-mcp-server-setup.gif)\n\n\nTo always use the latest version (auto-update on each restart), add `--auto-update`:\n\n```bash\nnpx @iterable/mcp setup --auto-update\n```\n\nBy default, the setup wizard configures the server in a safe, read‑only mode (no PII tools, no writes, no sends). To selectively enable elevated capabilities during setup, pass `--advanced`:\n\n```bash\n# Example: enable advanced setup to configure permissions\nnpx @iterable/mcp setup --advanced\n```\n\nWhat you'll choose (optional):\n- **User PII** (`ITERABLE_USER_PII`): access user profile data, including email addresses, phone numbers, and custom data fields.\n- **Writes** (`ITERABLE_ENABLE_WRITES`): create, update, and delete resources such as templates, lists, catalogs, campaigns, snippets, and user profiles.\n- **Sends** (`ITERABLE_ENABLE_SENDS`): send messages (email, SMS, push, in-app, WhatsApp), trigger campaigns and journeys, schedule and abort campaigns, and track events. Requires writes to be enabled. *Note: creating a blast campaign will schedule it for delivery, matching the behavior of the underlying Iterable API; there is no way to create a draft campaign. If you only need to draft content, you can do so with sends disabled by working with templates instead.*\n\n**IMPORTANT: Enabling writes and sends allows the AI agent to take real, potentially irreversible actions against your Iterable project, including sending messages to real users and deleting data. If you do not have the technical knowledge to properly review the agent's tool calls before they are executed, you should avoid enabling these flags, especially in production environments. It is entirely your choice to accept this risk. If you enable these capabilities, it is your responsibility to carefully review each action before allowing the agent to proceed.**\n\nNote that permission settings are saved per key (see key management section below), allowing you to enable different permissions for different projects, e.g. only enable writes and sends for a sandbox project and disable them in production.\n\n## What you can do\n\nSee the [available tools](TOOLS.md) for all tools with descriptions. All tools map directly to [Iterable API endpoints](https://api.iterable.com/api/docs).\n\nTry these prompts:\n- *\"Get details on campaign 12345\"*\n- *\"What email templates are available?\"*\n- *\"Show me all my product catalogs\"*\n- *\"What journeys are currently active?\"*\n- *\"Show me events for user@example.com from the last 30 days\"*\n- *\"Create a campaign called 'Holiday Sale' using template 456\"*\n- *\"Export all user data from January 2024\"*\n- *\"List users in my 'VIP Customers' list\"*\n\n## API Key Management\n\n**Key Storage:**\n\nAPI keys are stored in the `~/.iterable-mcp/keys.json` file and managed via the `npx @iterable/mcp keys` commands. On macOS the actual API key values are stored in the system Keychain. On Windows, API key values are encrypted using the Windows Data Protection API (DPAPI). On Linux, the API key values are stored directly in the file with restricted permissions (0o600).\n\nEach key is tied to its API endpoint (US, EU, or custom) and to its permissions (view PII, write operations, send messages).\n\n**How Key Selection Works:**\n- You can store multiple API keys with different names (e.g., \"production\", \"staging\", \"dev\")\n- Only ONE key is marked as **active** at a time\n- The MCP server automatically uses whichever key is currently active\n- Your first key is automatically set as active\n- Switch between keys using the `activate` command\n\n```bash\n# List stored keys (shows which one is active with ● ACTIVE badge)\nnpx @iterable/mcp keys list\n\n# Add a new key (interactive: prompts for name, region/endpoint, and API key)\n# Your first key becomes active automatically\nnpx @iterable/mcp keys add\n\n# Switch to a different key by name or ID (also switches endpoint)\nnpx @iterable/mcp keys activate production\nnpx @iterable/mcp keys activate staging\n\n# Update an existing key (interactive: prompts for new values)\nnpx @iterable/mcp keys update \u003cname-or-id\u003e\n\n# Delete a key by ID (requires ID for safety)\n# Note: Cannot delete the currently active key - activate another first\nnpx @iterable/mcp keys delete \u003ckey-id\u003e\n```\n\n## Advanced setup\n\n### Prefer a global install?\n\nIf you'd rather not use `npx`, you can install globally. This lets you use `iterable-mcp` as a shorthand for `npx @iterable/mcp`.\n\n```bash\npnpm add -g @iterable/mcp\niterable-mcp setup\n```\n\n**Note:** The setup command automatically configures the correct command path.\n\n### Claude Code\n\nThe `setup --claude-code` command automatically configures Claude Code by running `claude mcp add` for you.\n\nAlternatively, you can configure it manually:\n\n```bash\n# Add your API key first (see API Key Management section above)\nnpx @iterable/mcp keys add\n\n# Then configure Claude Code\nclaude mcp add iterable -- npx -y @iterable/mcp\n\n# Verify it was added\nclaude mcp list\n```\n\nIf you have already configured Claude Desktop successfully, you can run this command to copy your MCP server settings to Claude Code:\n\n```bash\nclaude mcp add-from-claude-desktop\n```\n\n**Note:** All of the above `claude mcp` commands will save the settings to `~/.claude.json`, which makes the configured MCP servers available across all projects. For shared, project-specific MCP configs, create a `.mcp.json` file in the root of your project.\n\nFor more information, see the [Claude Code MCP documentation](https://docs.claude.com/en/docs/claude-code/mcp).\n\n### Manual configuration (Cursor, Claude Desktop, Windsurf, Gemini CLI \u0026 Antigravity)\n\nThe above commands will automatically configure your AI tool to use the MCP server by editing the appropriate configuration file, but you can also manually edit the appropriate configuration file:\n- **Claude Desktop:** `~/Library/Application Support/Claude/claude_desktop_config.json`\n- **Cursor:** `~/.cursor/mcp.json`\n- **Windsurf:** `~/.codeium/windsurf/mcp_config.json`\n- **Antigravity:** `~/.gemini/antigravity/mcp_config.json`\n- **Gemini CLI:** `~/.gemini/settings.json`\n\nAll five use the same configuration format:\n\n**Recommended: Using key manager:**\n```bash\n# First, add your API key (interactive prompts)\nnpx @iterable/mcp keys add\n```\n\nThen edit your config file:\n```json\n{\n  \"mcpServers\": {\n    \"iterable\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@iterable/mcp\"]\n    }\n  }\n}\n```\n\nNo `env` section needed - API key and base URL are loaded automatically.\n\n**Alternative: Environment variables:**\n```json\n{\n  \"mcpServers\": {\n    \"iterable\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@iterable/mcp\"],\n      \"env\": {\n        \"ITERABLE_API_KEY\": \"your-iterable-api-key-here\",\n        \"ITERABLE_BASE_URL\": \"https://api.iterable.com\"\n      }\n    }\n  }\n}\n```\n\n### Using custom Node/NPX paths\n\nIf you need to use a custom path to node or npx (for example, if they are not in your PATH), you can set environment variables before running the setup command:\n\n```bash\n# Set custom paths\nexport ITERABLE_MCP_NODE_PATH=\"/path/to/custom/node\"\nexport ITERABLE_MCP_NPX_PATH=\"/path/to/custom/npx\"\n\n# Then run setup\nnpx @iterable/mcp setup --cursor\n```\n\nAlternatively, you can manually edit your configuration file (after adding your key):\n\n```json\n{\n  \"mcpServers\": {\n    \"iterable\": {\n      \"command\": \"/custom/path/to/npx\",\n      \"args\": [\"-y\", \"@iterable/mcp\"]\n    }\n  }\n}\n```\n\nNo `env` section is needed if using the key manager.\n\n### Environment variables\n\nVariables marked as **managed** are automatically configured by the key manager. They take precedence over environment variables when both are present. Setting environment variables directly is useful for CI/CD pipelines, Docker containers, or other non-interactive environments where the key manager isn't available.\n\n| Variable | Managed | Description |\n|----------|-------------|-------------|\n| `ITERABLE_API_KEY` | ✅ | Your Iterable API key. Required if not using key manager |\n| `ITERABLE_BASE_URL` | ✅ | Base URL for the Iterable API (default: `https://api.iterable.com`) |\n| `ITERABLE_USER_PII` | ✅ | Set to `true` to enable tools that access user PII data (default: `false`) |\n| `ITERABLE_ENABLE_WRITES` | ✅ | Set to `true` to enable tools that perform write operations (default: `false`) |\n| `ITERABLE_ENABLE_SENDS` | ✅ | Set to `true` to enable tools that can send messages (default: `false`). Requires writes to be enabled |\n| `ITERABLE_DEBUG` | | Set to `true` for API request logging |\n| `LOG_LEVEL` | | Set to `debug` for troubleshooting |\n\n### Custom endpoints\n\n- The CLI supports selecting the US or EU region, or entering a custom endpoint.\n- For security, HTTPS is required for custom endpoints. The only exception is localhost development:\n  - Allowed: `http://localhost:3000`, `http://127.0.0.1:8080`, `http://[::1]:4000`\n  - Not allowed: plain `http://` on non-local hosts (use `https://` instead)\n- When a non-`*.iterable.com` domain is provided, the CLI will ask for confirmation.\n\n## Troubleshooting\n\n- Claude CLI missing: install `claude` CLI, then re-run `npx @iterable/mcp setup --claude-code`.\n- macOS Keychain issues: Ensure Keychain is accessible and re-run setup if needed.\n\n### Client-specific limitations\n\n#### Windsurf (Codeium)\n\n**Tool limit:** Windsurf has a [maximum limit of 100 tools](https://docs.windsurf.com/windsurf/cascade/mcp) that Cascade can access at any given time. When all permissions are enabled (`ITERABLE_USER_PII=true`, `ITERABLE_ENABLE_WRITES=true`, `ITERABLE_ENABLE_SENDS=true`), the Iterable MCP server exposes **105 tools**, which exceeds this limit.\n\n**Workaround:** Use restricted permissions to stay under the 100-tool limit:\n- With default permissions (all disabled): 26 tools ✅\n- With PII only: 37 tools ✅\n- With PII + writes: 87 tools ✅\n- With all permissions: 105 tools ❌ (exceeds Windsurf limit)\n\nYou can configure permissions when adding a key:\n```bash\nnpx @iterable/mcp keys add --advanced\n```\n\nOr update an existing key's permissions:\n```bash\nnpx @iterable/mcp keys update \u003ckey-name\u003e --advanced\n```\n\n**Process persistence:** After switching API keys with `keys activate`, you must **fully restart Windsurf** (quit and reopen the application). Windsurf keeps MCP server processes running in the background, and they don't automatically reload when you switch keys.\n\n#### Antigravity\n\n**Tool limit:** Antigravity has a maximum limit of 100 tools per MCP server. When all permissions are enabled (`ITERABLE_USER_PII=true`, `ITERABLE_ENABLE_WRITES=true`, `ITERABLE_ENABLE_SENDS=true`), the Iterable MCP server exposes **105 tools**, which exceeds this limit.\n\n**Workaround:** Use restricted permissions to stay under the 100-tool limit:\n- With default permissions (all disabled): 26 tools ✅\n- With PII only: 37 tools ✅\n- With PII + writes: 87 tools ✅\n- With all permissions: 105 tools ❌ (exceeds Antigravity limit)\n\nYou can configure permissions when adding a key:\n```bash\nnpx @iterable/mcp keys add --advanced\n```\n\nOr update an existing key's permissions:\n```bash\nnpx @iterable/mcp keys update \u003ckey-name\u003e --advanced\n```\n\n## Contributing\n\nSee the [contributing guidelines](CONTRIBUTING.md) for development setup, building from source, and running tests.\n\n## Security\n\nSee the [security policy](SECURITY.md) for reporting vulnerabilities.\n\n## Beta Feature Reminder\n\nIterable's MCP server is currently in beta. MCP functionality may change, be\nsuspended, or be discontinued at any time without notice. This software is\nprovided \"as is\" and is open source and ready for you to experiment with. For\nmore information, refer to [Iterable Beta Terms](https://iterable.com/trust/beta-terms/).\n\n## License\n\nThis project is licensed under the MIT License. See the [license](LICENSE.md) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fiterable%2Fmcp-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fiterable%2Fmcp-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fiterable%2Fmcp-server/lists"}