Winnr

winnr-mcp

MCP server for the Winnr cold-email infrastructure API.

Lets Claude (web, mobile and desktop), ChatGPT, Claude Code, Cursor, Windsurf, VS Code (Copilot) and any other MCP client manage your domains, mailboxes, warming, inbox, pre-warmed marketplace and webhooks through natural language.

55 tools, 26 of them read-only, plus 8 resources and 5 prompt playbooks.

Two ways to run it:

Setup either way: app.winnr.app/mcp.

---

Hosted server

Add https://mcp.winnr.app/mcp as a custom connector / remote MCP server. The client registers itself (RFC 7591), sends you to Winnr to sign in, and you choose what it may do:

Scopes imply each other (purchase ⊃ write ⊃ read), and a session only ever *sees* the tools its scopes allow. Each grant is backed by a normal API token named MCP · , so it appears on the dashboard's API page and revoking it there cuts the assistant off.

# Claude Code, hosted

claude mcp add --scope user --transport http winnr https://mcp.winnr.app/mcp

---

Quick start (local)

1. Get a token

app.winnr.app/mcp (or API → Create Token). Tokens start with wnr_. Pick read-only if you only want reports and reply triage: every tool that creates, sends, buys or deletes is then hidden from the assistant. Add WINNR_NO_PURCHASES=true (or --no-purchases) to keep full write access while hiding the four tools that charge the card.

2. Install uv

The server runs with uvx, so uv must be installed once:

# macOS / Linux

curl -LsSf https://astral.sh/uv/install.sh | sh # or: brew install uv

Windows (PowerShell)

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

No uv? pip install winnr-mcp and use "command": "winnr-mcp" with no args instead.

3. Add the server to your client

Claude Desktop

Settings → Developer → Edit Config, then paste (macOS ~/Library/Application Support/Claude/claude_desktop_config.json, Windows %APPDATA%\Claude\claude_desktop_config.json). Fully quit and reopen Claude.

{

"mcpServers": { "winnr": { "command": "uvx", "args": ["winnr-mcp"], "env": { "WINNR_API_TOKEN": "wnr_your_token_here" } } } }

Claude Code

claude mcp add --scope user winnr -e WINNR_API_TOKEN=wnr_your_token_here -- uvx winnr-mcp

Then /mcp inside Claude Code shows Winnr as connected. Optional guided workflows (/winnr setup, /winnr health, /winnr export) come from winnr-claude-skills:

curl -sL https://raw.githubusercontent.com/winnr-app/winnr-claude-skills/main/install.sh | bash

Cursor

~/.cursor/mcp.json (global) or .cursor/mcp.json (project) — same JSON as Claude Desktop. Settings → MCP shows Winnr with a green dot when it is up.

Windsurf

~/.codeium/windsurf/mcp_config.json — same JSON. Refresh in Settings → Cascade → MCP Servers.

VS Code (Copilot agent mode)

.vscode/mcp.json:

{

"servers": { "winnr": { "type": "stdio", "command": "uvx", "args": ["winnr-mcp"], "env": { "WINNR_API_TOKEN": "wnr_your_token_here" } } } }

4. Try it

What's in my Winnr account, and how much capacity do I have left?

The assistant calls winnr_get_account and winnr_get_usage. The app.winnr.app/mcp page flips to Connected once the token has been used.

Configuration

CLI args take precedence over environment variables.

At startup the server calls GET /v1/account. An invalid token exits immediately with a clear message (a server that starts and then fails every call is worse). If the token is read-only, write tools are hidden automatically — no flag needed.

Spending money is always two steps

The four tools that charge the card — winnr_purchase_domains, winnr_purchase_prewarmed, winnr_purchase_prewarmed_batch, winnr_enable_warming — never charge on the first call. They return a live quote (availability re-checked, exact prices, monthly total) plus a confirmation_token valid for 10 minutes. The assistant shows the quote, gets an explicit yes, and calls again with the token. The quote is recomputed at that moment and the token is an HMAC over it, so if a price moved or a domain sold, the purchase is refused with a fresh quote instead of a surprise charge.

How the assistant is guided

The server ships instructions to the client (most hosts put them in the system prompt), and every tool carries MCP annotations (readOnlyHint, destructiveHint, idempotentHint) so hosts can ask for confirmation at the right moments. The instructions cover:

• IDs and async jobs (job_id → poll winnr_get_job)
• The four tools that charge the card (domain purchase, pre-warmed purchase ×2, warming enable) and the rule to get an explicit yes with the exact price first. Domain purchases re-check availability and price right before ordering and refuse the order if anything changed, so the confirmed total is the charged total
• Never retrying a purchase after a timeout without checking winnr_list_jobs
• Domain-name hygiene (brand-like names; no outreach/blast/bulk words)
• Cold-email ratios (2–5 mailboxes per domain, warm 2–3 weeks, modest daily sends)

It also ships resources (read-only records the host can attach to a conversation: winnr://account, winnr://usage, winnr://domains, winnr://domains/{id}, winnr://domains/{id}/dns-records, winnr://domains/{id}/dns-status, winnr://warming/overview, winnr://jobs/{id}) and prompts — parameterised playbooks: winnr_setup_infrastructure, winnr_health_check, winnr_reply_triage, winnr_connect_own_domain, winnr_scale_up.

Tools

Permission is the token scope the tool needs. Read tools are visible to every token.

Account, jobs, export

Domains

Mailboxes (email users)

Inbox

Warming

Pre-warmed marketplace

Webhooks