Instagram MCP Server

A production-quality Model Context Protocol server that exposes Instagram actions (posts, media containers/carousels, comments, direct messages, insights, Messenger profile) to Claude and ChatGPT. Built for personal, single-user use with Composio as the auth/action layer, deployed on Alpic.

This project mirrors the sibling Linkedin-alpic-mcp server's architecture exactly — same stack, same production fixes, just scoped to Instagram's Composio toolkit.

Features

• Curated tool scope — the Composio session and tool discovery are both scoped to exactly the 34 Instagram actions enabled for this account (see ENABLED_INSTAGRAM_TOOLS in src/composio_client.py), not every action Composio's Instagram toolkit could theoretically expose. Call instagram_mcp_list_tools to see the current live list with full JSON Schemas.
• Automatic Instagram auth — on startup, checks whether the fixed user is connected; if not, starts the OAuth flow, logs the authorization URL, and waits (bounded timeout) for the connection to complete.
• Structured logging — JSON logs via the stdlib logging module, best-effort rotating log file under logs/ (falls back to stdout-only on a read-only filesystem, e.g. serverless deploys).
• Local stats tracking — total/successful/failed calls, average latency, last execution, startup time, and uptime; best-effort persistence to a local JSON file (falls back to in-memory-only if unwritable).
• Health reporting — instagram_mcp_health reports server, Instagram connection, and Composio reachability.
• Never crashes — every Composio/network/auth failure (including Composio's own PermissionDeniedError for a playground-key/user_id mismatch) is caught and returned as a normal (but error-flagged) tool result, never an unhandled exception.
• Streamable-HTTP transport, binding PORT/HOST — ready for Alpic's hosting model.

Architecture

src/
├── server.py           # FastMCP app + entrypoint; wires everything together
├── composio_client.py  # Thin wrapper around the Composio SDK (Instagram toolkit only)
├── tool_registry.py    # Dynamic MCP tool list/dispatch: static utility tools + every Instagram action
├── config.py           # Settings loaded from environment / .env
├── logger.py           # Logging setup (best-effort file handler)
├── stats.py            # JSON-backed call statistics tracker (best-effort persistence)
├── health.py            # Health status aggregation
├── models.py             # Shared Pydantic models
└── utils.py              # Retry/backoff decorator, Timer

The four static tools (instagram_mcp_ping, instagram_mcp_health, instagram_mcp_version, instagram_mcp_list_tools) are always available. Every other tool name is a Composio Instagram action slug (e.g. INSTAGRAM_CREATE_POST, INSTAGRAM_GET_USER_INFO, INSTAGRAM_SEND_TEXT_MESSAGE, ...) — call instagram_mcp_list_tools at any time to see the current live list with descriptions.

Available Instagram Tools

The server's Composio session is scoped to exactly these 34 actions. Parameters below are best-effort, inferred from action names and the Instagram Graph API's conventions (this project's Composio account hadn't completed its Instagram connection yet at doc-writing time, so schemas weren't live-fetched the way the LinkedIn project's were) — call instagram_mcp_list_tools once connected to confirm exact fields.

Tool	Likely parameters	Use case
INSTAGRAM_CREATE_POST	image/video URL, caption	Publish a single-media feed post.
INSTAGRAM_CREATE_MEDIA_CONTAINER	media URL, caption, media type	Stage a single media item before publishing (required step before ..._PUBLISH).
INSTAGRAM_CREATE_CAROUSEL_CONTAINER	list of child media container IDs, caption	Stage a multi-image/video carousel post from already-created media containers.
INSTAGRAM_POST_IG_USER_MEDIA	media container params	Create IG user media (container-based posting flow).
INSTAGRAM_POST_IG_USER_MEDIA_PUBLISH	creation_id (container id)	Publish a previously staged media container (single or carousel).
INSTAGRAM_GET_POST_STATUS	container/media id	Check whether a staged container has finished processing and is ready to publish.
INSTAGRAM_GET_IG_MEDIA	media id	Get metadata for one media item (post).
INSTAGRAM_GET_IG_MEDIA_CHILDREN	carousel media id	List the individual media items inside a carousel post.
INSTAGRAM_GET_USER_MEDIA / INSTAGRAM_GET_IG_USER_MEDIA	ig user id, pagination	List media (posts) on an account, paginated.
INSTAGRAM_GET_IG_USER_STORIES	ig user id	List currently active stories for an account.
INSTAGRAM_GET_IG_USER_LIVE_MEDIA	ig user id	List currently live video sessions for an account.
INSTAGRAM_GET_IG_USER_TAGS	ig user id	List media where the account has been tagged.
INSTAGRAM_GET_IG_USER_CONTENT_PUBLISHING_LIMIT	ig user id	Check remaining publish quota (IG rate-limits posts per 24h).
INSTAGRAM_GET_POST_COMMENTS / INSTAGRAM_GET_IG_MEDIA_COMMENTS	media id, pagination	List comments on a post.
INSTAGRAM_POST_IG_MEDIA_COMMENTS	media id, comment text	Add a top-level comment to a post.
INSTAGRAM_REPLY_TO_COMMENT / INSTAGRAM_POST_IG_COMMENT_REPLIES	comment id, reply text	Reply to an existing comment.
INSTAGRAM_GET_IG_COMMENT_REPLIES	comment id, pagination	List replies to a comment.
INSTAGRAM_DELETE_COMMENT	comment id	Delete a comment or reply.
INSTAGRAM_GET_USER_INFO	(none — authenticated user)	Get your own connected account's profile info (username, id, account type).
INSTAGRAM_GET_USER_INSIGHTS	ig user id, metrics, period	Account-level insights (reach, impressions, follower demographics).
INSTAGRAM_GET_POST_INSIGHTS / INSTAGRAM_GET_IG_MEDIA_INSIGHTS	media id, metrics	Per-post insights (impressions, engagement, saves).
INSTAGRAM_LIST_ALL_CONVERSATIONS / INSTAGRAM_GET_PAGE_CONVERSATIONS	ig user id, pagination	List Instagram Direct conversations for the account.
INSTAGRAM_GET_CONVERSATION	conversation id	Get one conversation's message history.
INSTAGRAM_LIST_ALL_MESSAGES	conversation id, pagination	List messages within a conversation.
INSTAGRAM_SEND_TEXT_MESSAGE	recipient id, text	Send a text DM.
INSTAGRAM_SEND_IMAGE	recipient id, image URL	Send an image DM.
INSTAGRAM_MARK_SEEN	conversation/message id	Mark a DM/conversation as read.
INSTAGRAM_POST_IG_USER_MENTIONS	media id, comment/mention id	Handle a mention notification (e.g. tag reply flows).
INSTAGRAM_GET_MESSENGER_PROFILE	(none)	Get the account's Messenger platform profile config (greeting text, ice breakers, etc.).
INSTAGRAM_UPDATE_MESSENGER_PROFILE	profile fields to update	Update the Messenger platform profile config.
INSTAGRAM_DELETE_MESSENGER_PROFILE	field names to clear	Remove specific Messenger profile fields.

Installation

Requires Python 3.12+ and uv.

git clone <this-repo>
cd instagram-mcp
uv venv
uv pip install -e ".[dev]"

Configuration

Copy .env.example to .env and fill in your Composio credentials:

cp .env.example .env

Variable	Required	Default	Description
COMPOSIO_API_KEY	Yes	—	Your Composio API key. A project-scoped key, not a playground key — playground keys are locked to one bound user and will 403 on any other user_id.
COMPOSIO_USER_ID	Yes	—	Your Composio account's user id — tool calls and the Instagram connection are scoped to this user.
INSTAGRAM_AUTH_CONFIG_ID	No	Composio default	Use a specific Instagram auth config instead of the default one
LOG_LEVEL	No	INFO	DEBUG / INFO / WARNING / ERROR
LOG_DIR	No	logs	Directory for the rotating log file (best-effort — falls back to stdout-only if unwritable)
STATS_FILE	No	logs/stats.json	Path to the persisted stats JSON file (best-effort — falls back to in-memory-only if unwritable)
CONNECT_TIMEOUT_MS	No	300000 (5 min)	Max time to wait for Instagram OAuth to complete at startup
PORT	No	8000	Bind port (Alpic sets this automatically at deploy time)
COMPOSIO_CACHE_DIR	No (baked into Dockerfile)	—	Composio's SDK writes a cache dir at import time; set to a writable path (e.g. /tmp/.composio) on read-only-home sandboxes like Alpic's. Already set in Dockerfile.

Never hardcode COMPOSIO_API_KEY anywhere — it's read exclusively from the environment.

Running locally

uv run python -m src.server

On first run, if Instagram isn't connected yet, the server logs an authorization URL and waits for you to complete the OAuth flow in a browser before finishing startup (or continues anyway on timeout — the server never crashes on this, it just starts without a working connection until you finish the OAuth link).

Test it's alive — note streamable-HTTP requires the MCP handshake (initialize → notifications/initialized → your call, all carrying the same mcp-session-id response header), a bare tools/call will fail with "Missing session ID". Also: on Windows PowerShell, bare curl is aliased to Invoke-WebRequest and will silently mangle -X/-d — use curl.exe explicitly, or Git Bash's real curl.

curl -s -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"curl","version":"0"}}}'

Running with Docker

docker build -t instagram-mcp .
docker run --rm -p 8000:8000 --env-file .env instagram-mcp

Deploying to Alpic

npm install -g alpic   # once
alpic login            # or set ALPIC_API_KEY

alpic environment-variable add --env-file .env --environment-id <id>
alpic deploy --runtime python3.13

Alpic prints the live MCP server URL and a /try playground URL on success. Note: Alpic's managed Python runtime does not use this repo's Dockerfile — it builds directly from pyproject.toml with its own buildpack, running out of a sandboxed home directory that's read-only. That's why COMPOSIO_CACHE_DIR, best-effort file logging, and best-effort stats persistence all exist in this codebase — they were required to get a Composio-based server running on Alpic at all (see Troubleshooting below).

Connecting from Claude Desktop

1. Deploy first (or run locally and expose it, e.g. with ngrok http 8000).
2. In Claude Desktop: Settings → Connectors → Add custom connector.
3. Paste the Alpic-hosted MCP URL (ends in /mcp).
4. Claude will list instagram_mcp_ping, instagram_mcp_health, and every enabled Instagram action.

Connecting from ChatGPT

1. In ChatGPT: Settings → Connectors → Advanced settings → Developer mode (required for full custom tool calling, not just search/fetch).
2. Add custom connector, paste the Alpic-hosted MCP URL.
3. Enable the connector in a chat and ChatGPT can call any Instagram action directly.

Troubleshooting

Symptom	Likely cause	Fix
Server won't start / crashes immediately	COMPOSIO_API_KEY or COMPOSIO_USER_ID missing	Both are mandatory — set them before first deploy/run
403 ... user_id does not match the user this playground API key is locked to	You're using a Composio playground key	Mint a project-scoped API key in the Composio dashboard instead — playground keys are hard-locked to one bound user server-side, no client-side user_id can override that
Alpic build fails: Read-only file system: '/home/.../.composio'	Composio's SDK creates a cache dir at import time; Alpic's sandbox $HOME is read-only	Set COMPOSIO_CACHE_DIR=/tmp/.composio (already in this repo's Dockerfile, but Alpic ignores the Dockerfile for its managed Python runtime — add it as an Alpic environment variable too: alpic environment-variable add --name COMPOSIO_CACHE_DIR --value /tmp/.composio --environment-id <id>)
Alpic build fails: Read-only file system: '.../logs/instagram-mcp.log'	Same read-only-filesystem class of issue, this time our own log/stats file writes	Already fixed in this codebase (logger.py/stats.py both fall back gracefully) — if you still see this, you're running an older copy
instagram_mcp_health shows instagram_connected: false	OAuth never completed	Check server logs for the authorization URL, visit it, then call instagram_mcp_list_tools to refresh
instagram_mcp_health shows composio_reachable: false	Bad API key or Composio outage	Verify COMPOSIO_API_KEY is valid; check https://status.composio.dev
A Instagram tool call errors out	Expired auth, missing scope, or bad input	The error message is returned verbatim from Composio/Instagram in the tool result — read it, it's usually actionable
curl from PowerShell gives Not Acceptable: Client must accept text/event-stream despite the header being set	curl in PowerShell is aliased to Invoke-WebRequest, which silently sends GET instead of your intended POST	Use curl.exe explicitly, Invoke-RestMethod, or Git Bash's real curl

Testing

uv run pytest

License

MIT — see LICENSE.