You already have Claude Desktop, Claude Code, or Cursor open more hours a day than the PushEngage dashboard. Every time you need to check a click rate or send a notification, you tab away from the window where the actual work is happening. PushEngage MCP setup closes that gap: one npx command, a browser sign-in, and PushEngage’s tools sit inside the same chat session you’re already using to write code, debug a workflow, or answer a question from your team.
This is the complete setup guide: install, the two environment variables worth knowing about, the first login, and the three specific things that break the connection when it doesn’t just work on the first try. By the end, you’ll have an authenticated session with a site selected, not just a green “connected” indicator.
What you’ll be able to do once you’re connected
@pushengage/mcp ships 27 tools across 10 domains, and once you’re authenticated against a site, all of them are one sentence away instead of a dashboard click away. A few examples of what that looks like once setup is done:
- Send a push notification now, schedule it for a specific time, or set up a recurring send — in each subscriber’s local timezone if you ask for it.
- Run an A/B test between two headlines and let the assistant report back on click rate once results are in.
- Build a segment or an audience group from a plain-language description instead of a rules UI.
- Pull analytics as a lifetime summary or as a day-by-day time series.
- List your drip campaigns, triggered campaigns, and workflows to check what’s actually running.
- Read your site’s settings, service worker configuration, and chat widget setup.
None of that requires the assistant to have your PushEngage password, and none of it requires you to leave your editor or terminal. PushEngage runs this integration for an account base of 25,000+ business owners across 150+ countries, sending 15.2 billion notifications in the last 30 days. The MCP server talks to the same production API that volume runs on, not a sandboxed demo.
Before you start: what you need
Three things, and you likely already have at least two of them:
- A PushEngage account — free or paid, with at least one site added. The MCP server does not create a site for you; it operates on sites you’ve already set up in your PushEngage dashboard.
- Node.js 18 or newer — the assistant runs the server via
npx, which ships with Node. Check withnode -vin a terminal. - An MCP-capable client — Claude Desktop, Claude Code, Cursor, or any other client that speaks MCP over standard input/output (stdio).
One thing worth stating plainly before you start editing config files: @pushengage/mcp runs locally on your machine over stdio. There’s no remote server to point at and no hosted connector URL. The client launches the process, and the process talks to PushEngage’s API on your behalf. If a setup guide for a different tool tells you to paste in a remote endpoint, that’s a different kind of MCP server than this one.
Setting up the server in Claude Desktop, Claude Code, and Cursor
No global install. npx fetches @pushengage/mcp on demand the first time your client launches it, using the exact command npx -y @pushengage/mcp. You add that command to your client’s MCP configuration, restart the client, and the server appears in your tool list.
Each client keeps its configuration in a different place.
Claude Desktop
Edit ~/Library/Application Support/Claude/claude_desktop_config.json on macOS (or the equivalent path on your platform):
{
"mcpServers": {
"pushengage": {
"command": "npx",
"args": ["-y", "@pushengage/mcp"]
}
}
}Restart Claude Desktop. The “pushengage” server should appear in your tool list.
Cursor
Edit ~/.cursor/mcp.json:
{
"mcpServers": {
"pushengage": {
"command": "npx",
"args": ["-y", "@pushengage/mcp"]
}
}
}Claude Code
Claude Code speaks MCP over stdio the same way Claude Desktop and Cursor do, so the same command/args shape works if you edit its MCP config file directly. If you’d rather not hand-edit JSON, Claude Code also accepts servers through its own claude mcp add CLI command, which is general Claude Code behavior rather than anything specific to PushEngage. Check Claude Code’s own docs for the exact flag syntax if you go that route.
Any other MCP client
If your client isn’t one of the three above, the underlying requirement is the same everywhere: configure it to run npx -y @pushengage/mcp as a stdio server. That’s the entire install step, regardless of which client reads the config.
Naming the connection and isolating tokens: PE_MCP_CLIENT_NAME and PE_MCP_CONFIG_PATH
No configuration beyond the install step is required. The server talks to PushEngage’s production API by default; two environment variables exist for less common setups:
| Env var | Default | Purpose |
|---|---|---|
PE_MCP_CLIENT_NAME | AI assistant | The label shown on the PushEngage authorize screen as the app requesting access. Set it if you want something more specific, like "Claude Desktop". |
PE_MCP_CONFIG_PATH | ~/.pushengage/mcp.json | Where the access token is stored. Set this to run more than one PushEngage account side by side. Must be an absolute path — no ~ expansion. |
Most single-account setups never need to touch either variable. PE_MCP_CLIENT_NAME is a cosmetic convenience, useful if you want the authorize screen to say something more legible than “AI assistant” when you’re the one clicking Authorize. PE_MCP_CONFIG_PATH matters the moment you need a second, separate token file, which is exactly the case covered next.
First run: logging in and picking a site
Authentication is browser-based, so the assistant never sees your PushEngage password. The flow is three steps, and it’s worth walking through what each one actually calls under the hood:
- Ask the assistant to log in. In plain language: “Log me into PushEngage.” This invokes
pushengage_auth_login, which opens a browser tab to the PushEngage authorize page. - Click Authorize. The dashboard sends the token to the server as a POST request — it never appears in a URL, browser history, or access log. The token is saved locally with
0600permissions, readable only by your user. - Ask the assistant to show your sites, then pick one. “Show my PushEngage sites” calls
pushengage_list_sites; “Use site 12345” callspushengage_select_site. The selection is remembered across restarts, and every site-scoped tool acts on it unless you explicitly pass a differentsite_id.
The tools involved, by name:
| Tool | Purpose |
|---|---|
pushengage_auth_login | Opens the browser to PushEngage and stores the token on success. |
pushengage_auth_status | Shows whether you’re authenticated and which site is currently selected. |
pushengage_list_sites | Lists the PushEngage sites your account can access. |
pushengage_select_site | Sets the current site the other tools will act on. |
Once you’ve picked a site, run pushengage_auth_status (asking “what’s my PushEngage auth status” is enough) and confirm it reports both an authenticated session and a selected site before you try anything else. That’s the actual finish line for setup, not the moment the client first shows the server as connected.
Troubleshooting, by cause
Most connection problems trace back to one of three specific causes. Diagnose in this order.
The server won’t connect at all, and your client shows “Connection closed.” This is almost always a PATH problem, not a bug in the server. Claude Desktop, Cursor, and similar clients launch from your Dock or Finder, not from a terminal, so they never load your shell’s startup files. If Node was installed through a version manager (nvm, fnm, volta), the client can’t find npx at all. The process never starts, and you get a generic connection error instead of a clear “command not found.” Run which npx in a terminal to get the absolute path, then point your client at it directly:
{
"mcpServers": {
"pushengage": {
"command": "/absolute/path/from/which-npx",
"args": ["-y", "@pushengage/mcp"],
"env": {
"PATH": "/absolute/folder/containing/that/npx:/usr/bin:/bin:/usr/sbin:/sbin"
}
}
}
}Restart the client after editing. If which npx instead prints a path under /usr/local/bin or /opt/homebrew/bin, a version manager likely isn’t your issue; check the client’s own MCP logs for the actual error.
[AUTH_EXPIRED]. Your token expired. Ask the assistant to log in again — that’s the entire fix.
[NO_SITE_SELECTED]. You’re authenticated, but no site is chosen yet. Call pushengage_list_sites, then ask to use one of the returned sites, before trying any site-scoped tool again.
One more case worth knowing about even though it’s not an error: if the browser doesn’t open automatically, you’re likely in a headless or remote session (SSH, a container). The authorize URL prints to the terminal running the server. Open it manually.
Running more than one PushEngage account or client
If you manage PushEngage for more than one brand, or you’re an agency running MCP against several client accounts, the fix is PE_MCP_CONFIG_PATH from earlier: register the server under two different names, each with its own path so the tokens don’t collide.
{
"mcpServers": {
"pushengage-client-a": {
"command": "npx",
"args": ["-y", "@pushengage/mcp"],
"env": {
"PE_MCP_CONFIG_PATH": "/Users/you/.pushengage/mcp-client-a.json",
"PE_MCP_CLIENT_NAME": "Claude Desktop (Client A)"
}
},
"pushengage-client-b": {
"command": "npx",
"args": ["-y", "@pushengage/mcp"],
"env": {
"PE_MCP_CONFIG_PATH": "/Users/you/.pushengage/mcp-client-b.json",
"PE_MCP_CLIENT_NAME": "Claude Desktop (Client B)"
}
}
}
}Log in under each server name separately, authorizing whichever PushEngage account you choose in the browser each time. Each server entry keeps its own token file, so switching between client accounts is a matter of which tool name you call, not a re-login every time. If this is your actual use case, the series has a full walkthrough of running multiple PushEngage client accounts from one AI assistant.
What to do once you’re connected
With auth done and a site selected, the 27 tools break down into a few practical groups worth knowing by name, not just by count.
For the day-to-day work of running campaigns, the series covers how to send and schedule push notifications from your AI assistant instead of the dashboard, and how to A/B test push notifications and let AI pick the winner by click rate. For building your list, there’s a full guide to build subscriber segments in plain English.
For measurement, read push notification analytics through your AI assistant walks through lifetime summaries and day-by-day time series. Those are the same analytics tools that make an A/B test result or a campaign send worth reporting on, not just running. The series also covers auditing drip campaigns and workflows to check what’s actually active, and managing the chat widget that surfaces WhatsApp and other channels on-site.
For site-level work, change PushEngage site settings from an AI assistant covers timezone, geolocation, and service worker configuration. And if you’re setting this up for more than one PushEngage account, the agency-focused post on running multiple PushEngage client accounts from one AI assistant (linked above) goes deeper than the config example in this guide.
If you’re setting this up for someone less technical (a founder who wants the AI assistant handling PushEngage day to day without touching a config file themselves), a non-technical founder’s first week with PushEngage MCP is the narrative version of this same setup, written for that reader.
Setup itself works the same regardless of your PushEngage plan. Every PushEngage plan, including the free tier, supports the MCP server. If you’re deciding which plan fits before you connect anything, PushEngage’s pricing page has the current tiers.
