# Instagram MCP server for Claude, Cursor and AI agents

> Markdown version of https://instaoutreach.com/docs. Facts as of October 17, 2026.

Connect InstaOutreach to Claude Code, Cursor, or any MCP client and manage Instagram accounts by chat: add accounts, start warmup, check health, draft campaigns. Every limit is enforced server-side; clients can't bypass the anti-ban gates.

## What is this

MCP (Model Context Protocol) is an open standard that lets AI clients discover and call tools on a server. InstaOutreach exposes a hosted MCP server, so your AI assistant becomes a power-console for your outreach fleet. You connect by signing in from your client and choosing an access level; the connection maps to your workspace and nothing else.

## Quick start

1. Add the server: `claude mcp add --transport http instaoutreach https://instaoutreach.com/mcp`
2. On first use your browser opens. Sign up or sign in, pick what the agent may do and press **Allow**. No token to copy.
3. Ask your assistant: "how are my accounts doing?" or paste login data to onboard.

## Sign in or use a token

Clients that support MCP sign-in (OAuth 2.1 with PKCE, found from the server's 401 answer) need nothing else. For a client without sign-in, create a token in Settings, AI agents (https://instaoutreach.com/dashboard/settings). It is shown **once** and starts with `iom_`. Revoke a connection or token from the same screen; the client loses access at once.

## Connect a client

Server URL: `https://instaoutreach.com/mcp`, transport **HTTP**, auth **OAuth sign-in** or a Bearer token.

### Claude Code

```sh
claude mcp add --transport http instaoutreach https://instaoutreach.com/mcp
```

### Cursor / Claude Desktop (mcp.json)

```json
{
  "mcpServers": {
    "instaoutreach": { "url": "https://instaoutreach.com/mcp" }
  }
}
```

### Client without sign-in

```sh
claude mcp add --transport http instaoutreach https://instaoutreach.com/mcp \
  --header "Authorization: Bearer iom_your_token_here"
```

Setting up with an AI agent? Point it at https://instaoutreach.com/agents.md

## Tools reference

### Every level

- `list_accounts`: List every sending account in your org with status, platform, warmup day, health, proxy and login state.
- `get_account`: Full detail for one account by username (never returns the password or 2FA secret). Params: `username`*.
- `list_proxies`: List proxies in your org with status, geo and whether each is in use.

### Build or Build and send

- `onboard_account`: Add a sending account. NOTE: for security, credentials (password + 2FA) are NEVER accepted over MCP: they would pass through the AI model. This returns a link to add the account securely via the dashboard's paste flow. Params: `username`*.
- `enroll_lead`: Enroll an Instagram handle into outreach (campaign 'Sirius leads' by default). Pass external_ref = a CRM lead id to link it, so funnel status (queued/dm_sent/replied/booking) writes back to that lead. Params: `ig_username`*, `external_ref`, `campaign`.
- `pause_account`: Pause an account (stops all engine activity for it). Params: `username`*.
- `add_proxy`: Add a proxy to your org. Params: `label`*, `host`*, `port`*, `username`, `password`, `scheme`, `geo`.
- `set_order_meta`: Save the purchase order number / source link for an account. Params: `username`*, `order_number`, `purchase_url`.
- `create_campaign`: Create a DRAFT (paused) campaign. Never auto-sends: you launch it from the dashboard. Params: `name`*, `offer`, `dm_prompt`, `engagement_action`.

### Build and send only

- `start_warmup`: Start (or resume) the warmup ramp for an account. Params: `username`*.
- `mark_warmed`: Skip warmup: mark an already-aged, actively-used account as active so it can DM immediately. Not for cold accounts. Params: `username`*.
- `set_warmup_config`: Set an account's warmup window (warmup_days_to_dm, days before first DM; 0 = already warm) and/or daily DM limit (max 75). Usage simulation always runs regardless. Params: `username`*, `warmup_days_to_dm`, `daily_dm_limit`.
- `bind_proxy`: Bind an existing proxy (by label) to an account. Params: `username`*, `proxy_label`*.

\* required. Destructive actions (delete account, change billing) are intentionally **not** exposed over MCP.

## Access levels and safety

- **Read only** (`read`): See stats, leads and replies.
- **Build** (`build`): Also add leads and draft campaigns. Nothing is sent.
- **Build and send** (`send`): Also start and pause sending, within your safety limits.
- You pick the level when you approve the connection; Build is the default. Older `operator` tokens count as Build and send.
- Tokens are scoped to your organization. The server resolves the org from the token, so a client can never act on another tenant.
- Read tools never return passwords or 2FA secrets.
- Every change made by an agent is written to an audit log.

## Limits and abuse prevention

The MCP server is a thin layer over the same engine the dashboard uses, so all guardrails apply regardless of caller:

- Rate limit: 120 calls/min per token.
- Seat limits and plan entitlements enforced server-side: onboarding past your plan is refused.
- Warmup gating: a per-account window (default 14 days, set it yourself; 0 for already-warm accounts) before the first DM. There is no "mass-DM" tool.
- Usage simulation (feed, likes, stories) runs continuously, before, during and after DMing, to keep accounts looking human.
- Per-account daily DM limit (you set it, hard cap 75) and an abuse circuit-breaker stay in force.

## Example prompts

- How are my accounts doing? Anything unhealthy?
- Add the account taylor_demo and start warmup
- Start warmup on every account still marked new
- Which accounts are still warming up?
- Create a draft campaign called “Spring” targeting candle buyers

## Troubleshooting

- **401 unauthorized**: Not signed in, or the connection was revoked. Run `/mcp` in Claude Code (or reconnect in your client) and sign in again.
- **"Needs a higher access level"**: The tool is above the level you approved. Revoke the connection in Settings, AI agents, connect again and pick Build or Build and send.
- **429 rate limited**: You exceeded 120 calls/min. Wait a moment and retry.
- **"seat limit reached"**: Add seats in Billing before onboarding more accounts.

HTTP API reference: https://instaoutreach.com/docs/api