SharePush MCP server

SharePush runs an MCP server. MCP (Model Context Protocol) is the open standard AI assistants use to read data from other apps. Connect it once, then ask about your push campaigns in plain language:

"Which campaigns had the best CTR last month?"
"Are my clicks going up or down compared to the previous 30 days?"
"What title structures and topics earn the most clicks? Give me rules and three example titles."

The assistant looks the numbers up in your account and answers with them. The connection is read-only by default. If you allow it, the assistant can also draft and schedule campaigns, for example "Draft a push for this article and schedule it for 18:00". It never sends immediately, and never edits or deletes existing campaigns.

 1https://sharepush.io/mcp

The MCP tab of Settings → API Tokens & MCP has the same address with a copy button, and lists every assistant connected to your team. Open it from your profile menu, top right.

#Two ways to connect

Sign in (no token). claude.ai, Claude Desktop, ChatGPT, Codex, Claude Code, Cursor, VS Code, Gemini CLI and Zed send you to a SharePush page to approve the connection. SharePush then creates a token for that app. There is nothing to copy.
Paste a token. Create one in Settings → API Tokens & MCP with the read ability and give it to your client as Authorization: Bearer YOUR_API_TOKEN. Use this for clients without sign-in, or when you want a token limited to some sites. Add the create and update abilities to let the assistant draft, schedule and cancel campaigns.

When you sign in, the approval page has a box, Also allow it to draft and schedule campaigns. It is off by default: leave it off and the connection only reads.

Either way:

Only the team owner and managers can connect an assistant.
It is free on every plan, Free included. Without the HTTP API in your plan, MCP answers up to 1,000 requests an hour; with it, MCP calls share the plan's hourly API limit.
Every connection is an API token. It is listed under Connected assistants in the MCP tab of Settings → API Tokens & MCP, with the app that uses it. Disconnect it there at any time.

#Installation

Pick your app. Each tab has the exact steps, the configuration to paste, and the one detail that most often goes wrong.

Claude

claude.ai, Claude Desktop and the Claude mobile apps share one connector list, so you set it up once.

1 Open Customize → Connectors, click + and choose Add custom connector. On Team and Enterprise plans an owner adds it under Organization settings → Connectors, then members connect.
2 Paste the server address. Leave the OAuth client ID and secret under Advanced settings empty.
3 Click Connect. A SharePush page opens: sign in, choose the team and click Allow access.

Server address

https://sharepush.io/mcp

Good to know: Claude connects from its own servers, so SharePush must be reachable from the internet. Pasting a token is not an option here: sign-in is the way in.

Codex

The same steps work in the Codex app, the Codex CLI and the Codex IDE extension.

1 Codex app: Settings → MCP servers → Add server. Name it sharepush, choose Streamable HTTP, paste the address, save, then click Restart and Authenticate.
2 CLI or IDE extension: add the block below to ~/.codex/config.toml, then run codex mcp login sharepush and approve in the browser.
3 Start a new conversation and type /mcp: sharepush should list its tools.

~/.codex/config.toml

[mcp_servers.sharepush]
url = "https://sharepush.io/mcp"

codex mcp login sharepush

With a token instead (config.toml)

[mcp_servers.sharepush]
url = "https://sharepush.io/mcp"
bearer_token_env_var = "SHAREPUSH_TOKEN"

Good to know: bearer_token_env_var takes the name of an environment variable (then export SHAREPUSH_TOKEN=…), never the token itself. Tools load when a conversation starts, so open a new one after connecting.

Cursor

Add to Cursor

Use the button, or add the server to ~/.cursor/mcp.json (every project) or .cursor/mcp.json (one project).

1 Click Add to Cursor and confirm in Cursor, or paste the block below into mcp.json.
2 Cursor signs in with OAuth: approve the SharePush page when it opens.

~/.cursor/mcp.json

{
    "mcpServers": {
        "sharepush": {
            "url": "https://sharepush.io/mcp"
        }
    }
}

With a token instead

{
    "mcpServers": {
        "sharepush": {
            "url": "https://sharepush.io/mcp",
            "headers": {
                "Authorization": "Bearer ${env:SHAREPUSH_TOKEN}"
            }
        }
    }
}

Good to know: Cursor reads environment variables as ${env:NAME} inside mcp.json, so the token can stay out of the file.

VS Code

Install in VS Code

For GitHub Copilot agent mode. Use the button, run MCP: Add Server from the command palette, or create .vscode/mcp.json.

1 Install with the button, or paste the block below into .vscode/mcp.json.
2 On first use VS Code opens the browser: sign in to SharePush and click Allow access.

.vscode/mcp.json

{
    "servers": {
        "sharepush": {
            "type": "http",
            "url": "https://sharepush.io/mcp"
        }
    }
}

With a token instead

{
    "inputs": [
        {
            "type": "promptString",
            "id": "sharepush-token",
            "description": "SharePush API token",
            "password": true
        }
    ],
    "servers": {
        "sharepush": {
            "type": "http",
            "url": "https://sharepush.io/mcp",
            "headers": {
                "Authorization": "Bearer ${input:sharepush-token}"
            }
        }
    }
}

Good to know: The top-level key is servers, not mcpServers as in other clients.

Gemini CLI

One command, or an entry in ~/.gemini/settings.json.

1 Run the command below. -s user registers it for every project; the default is the current one.
2 Gemini CLI starts the sign-in on its own the first time the server answers 401. You can also run /mcp auth sharepush.

Terminal

gemini mcp add --transport http -s user sharepush https://sharepush.io/mcp

~/.gemini/settings.json

{
    "mcpServers": {
        "sharepush": {
            "httpUrl": "https://sharepush.io/mcp"
        }
    }
}

With a token instead

gemini mcp add --transport http -s user \
  -H "Authorization: Bearer YOUR_API_TOKEN" sharepush https://sharepush.io/mcp

Good to know: Use httpUrl, not url: in Gemini CLI url means the older SSE transport. Sign-in needs a local browser, so it won’t work over SSH.

#What the assistant can look up

Tool	What it answers
`list-sites`	Which sites and networks the connection can read. The assistant calls this first.
`campaign-performance`	Campaigns sent in a date range, with sent, delivered, viewed, clicked, closed and CTR, ranked. Can be filtered by manual or RSS, topic, or search text.
`performance-trend`	Deliveries, clicks and CTR day by day or week by week, compared with the previous period of the same length.
`live-activity`	What is happening right now: deliveries, clicks and closes over the last minutes (up to 3 hours), which campaigns are generating them and whether each is picking up or slowing down, how far the latest sends have rolled out, and older campaigns still earning clicks.
`campaign-detail`	One campaign in full: its text, every dispatch, and the A/B test result if the campaign ran one.
`content-patterns`	What your best notifications have in common: CTR by topic, by title length, by title and body features (questions, numbers, emoji, two-part titles, quotes…), by send hour and by weekday, with your best and worst titles as examples.
`identified-audience`	Your logged-in readers against anonymous ones. How many subscribers you can identify, how each group engages (CTR, share of people who click), your most engaged identified readers with their top interests, and the topics each group clicks.
`export-subscribers`	A CSV of your subscribers, filtered by status, subscription date, last activity, country, topic or identified readers. Returns a download link.
`export-campaign-activity`	A CSV of one campaign's audience activity: a row per subscriber event (delivered, viewed, clicked, closed). Returns a download link.

#Identified readers

A subscriber is identified when your site gives the SharePush SDK an external_id: your own id for the reader, sent when they are logged in to your site. Everyone else is anonymous.

identified-audience returns those ids, never names or emails. That is on purpose: the id is the key into your user database. If your assistant can also read that database (through another MCP server, for example), ask it to join the two: "Who are my 20 most engaged push readers, and which of them pay for a subscription?"

#Exports

The two export tools work like OneSignal's: the assistant gets a download link and the number of rows, never the rows themselves. Your subscriber list stays between SharePush and your browser.

Open the link to download the CSV. It is built when you open it, so it shows the data as of that moment.
Links last 3 days, and stop working sooner if the connection that created them is removed.
Subscribers: by default UID, external ID, country, status, subscription date, browser and OS. Ask for extra columns (referrer, behavioural and acquisition category, welcome window, pause, push token) when you need them. It is the same data as the export on the Subscribers page.
Campaign activity: the time on your site's clock, the event, the A/B variant and dispatch, and the subscriber's UID, external ID, platform, OS, browser and country.
IP addresses are never exported, and neither are user agents.

#What the assistant can do, if you allow it

Tool	What it does	Ability
`create-campaign`	Saves a campaign as a draft, or schedules it at least 10 minutes ahead. It can target countries, browsers and operating systems. It first returns a preview with the estimated reach and saves nothing; the assistant creates the campaign only on a second call.	`create`
`cancel-scheduled-campaign`	Puts a scheduled campaign back in drafts before it goes out.	`update`

Nothing goes out immediately. A scheduled campaign always leaves at least 10 minutes after it was created, so you can cancel it from the assistant or from the Campaigns page.
Drafts wait for you. A draft is sent only when someone sends it from the dashboard, to the whole audience of the site.
Your daily delivery cap still applies. The assistant cannot bypass it.
Across a network, one campaign is created for each site, and the schedule time is in UTC.

Some apps also offer the server's ready-made campaign-report prompt, which runs all of the above and writes a complete report with recommendations. In Claude Code it appears as /mcp__sharepush__campaign-report.

#How to read the numbers

CTR = clicked ÷ delivered, as a percentage. It is the same figure as on the Campaigns page.
Delivered is confirmed by the subscriber's device, and some devices confirm late or not at all. That is why sent and delivered can differ.
Days and hours use each site's own clock. Across a network, which can span several time zones, UTC is used.
Small samples are unreliable. A campaign with 3 clicks out of 5 deliveries has a 60% CTR, but it proves nothing. The pattern analysis leaves out dispatches with fewer than 50 deliveries by default. Ask for a lower threshold if your sends are smaller.
Patterns are correlations. "Titles with a number get more clicks" means the two go together, not that the number causes the clicks. Confirm a rule with an A/B test before you rely on it.

#Good questions to ask

"Compare my RSS and manual campaigns over the last 90 days."
"Which topics beat my average CTR, and which ones drag it down?"
"Take my 10 best and 10 worst titles. What is structurally different between them?"
"What is the best hour and weekday to send, according to my own data?"
"Summarise the A/B tests I ran this quarter and what each one taught me."
"Write five titles for tomorrow's article about X, following my best-performing pattern."
"Do my logged-in readers click more than anonymous ones? What does each group read?"
"Export the subscribers who joined this month but haven't been active since, with their category."
"Give me a CSV of everyone who clicked yesterday's campaign."

#Troubleshooting

What you see	What it means
The app shows the server as failed or with 0 tools	It connected without credentials. Finish the sign-in (Authenticate, `codex mcp login sharepush`, `/mcp` in Claude Code), or check the token in your configuration.
The sign-in page says not registered	The app kept an old registration. Remove the server from the app and add it again.
`401 API token is required` / `Invalid API token`	The `Authorization: Bearer …` header is missing, or the token was revoked or mistyped.
`401 API token has expired`	Create a new token and update your configuration.
`403 … team owner and managers only`	The token belongs to a member with another role. Ask the team owner or a manager to connect.
`429 … limit exceeded`	You have used the hourly allowance. Wait for the next hour.
Site … is not readable with this token	The token is limited to other sites. Ask the assistant to run `list-sites`, or use a token that covers that site.
Codex: `bearer_token_env_var` shows your token	That field wants the name of an environment variable, not the token. See the Codex tab.
Gemini CLI connects but finds no tools	Use `httpUrl`, not `url`, in `settings.json`.
An export link says it no longer works	The link is older than 3 days, or the connection that created it was removed. Ask for the export again.

#Security

Treat a token like a password. Anyone who has it can read the same data.
Give each assistant its own connection. Signing in does this for you. You can then disconnect one app without breaking the others.
Disconnect from Settings → API Tokens & MCP. Removing a token cuts off every app that uses it immediately.

SharePush MCP server

#Two ways to connect

#Installation

Claude

ChatGPT

Codex

Claude Code

Cursor

VS Code

Gemini CLI

Windsurf

Zed

#What the assistant can look up

#Identified readers

#Exports

#What the assistant can do, if you allow it

#How to read the numbers

#Good questions to ask

#Troubleshooting

#Security