Instagram MCP Server

A professional, well-structured MCP (Model Context Protocol) server for managing and posting Instagram content — PDF to images, carousel batches, auto-posting, and Cloudinary hosting.

Features

📸 Content management — list, view, delete, archive local images
✏️ Metadata — captions & hashtags per content item
📱 Post to Instagram — single image or carousel posts via Graph API
🖼️ PDF → Images — convert PDF pages to PNGs (poppler)
🎠 Carousel batches — group images into 2-10 image carousels
☁️ Cloudinary — temporary image hosting + auto-cleanup
🔑 Token diagnostics — debug token expiry, scopes, and meta error codes

Project Structure

instagram-mcp/
├── src/instagram_mcp/          # Main package
│   ├── config.py               # Env, constants, paths
│   ├── logging_setup.py        # Console + file logging
│   ├── errors.py               # Meta error parsing + guidance
│   ├── server.py               # FastMCP registration (thin)
│   ├── __main__.py             # python -m instagram_mcp
│   ├── services/               # External integrations
│   │   ├── instagram.py        #   Graph API client
│   │   ├── cloudinary.py       #   Upload/delete/verify
│   │   └── pdf.py              #   PDF → images
│   ├── storage/                # Local data access
│   │   ├── content.py          #   File resolution
│   │   └── metadata.py         #   JSON load/save
│   └── tools/                  # MCP tool implementations
│       ├── content_tools.py
│       ├── metadata_tools.py
│       ├── instagram_tools.py
│       ├── cloudinary_tools.py
│       └── carousel_tools.py
├── scripts/                    # CLI utilities
│   ├── check_token.py          #   Validate token + scopes
│   └── refresh_token.py        #   Extend long-lived token
├── tests/                      # pytest suite (mocked HTTP)
├── content/                    # Your media files (unchanged)
├── archive/                    # Archived content
├── logs/                       # Log files
├── server.py                   # Backward-compatible entry point
└── pyproject.toml              # Package config

Installation

# Create & activate venv (Windows)
python -m venv .venv
.\.venv\Scripts\Activate.ps1

# Install package (editable)
pip install -e .

Configuration

Copy .env.example → .env and fill in:

# Instagram (required for posting)
INSTAGRAM_ACCESS_TOKEN=your_token_here
INSTAGRAM_BUSINESS_ACCOUNT_ID=your_account_id_here

# Cloudinary (required for publish_image / carousels)
CLOUDINARY_CLOUD_NAME=...
CLOUDINARY_API_KEY=...
CLOUDINARY_API_SECRET=...

# Optional
INSTAGRAM_API_VERSION=v23.0
LOG_LEVEL=INFO
DELETE_LOCAL_AFTER_PUBLISH=false

Running the Server

# Option 1: Backward-compatible (Claude Desktop config)
python server.py

# Option 2: As a package
python -m instagram_mcp

# Option 3: Console script (after pip install -e .)
instagram-mcp

CLI Utilities

# Check your token's validity, expiry, and scopes
python scripts/check_token.py

# Info on refreshing a long-lived token (60 days)
python scripts/refresh_token.py

Testing

pip install -e ".[dev]"
pytest

MCP Tools

Tool	Purpose
`list_content`	List local images in content dir
`get_content`	Get file metadata (mime, size)
`manage_content`	list / delete / archive content
`manage_metadata`	Update / view / clear captions & hashtags
`test_instagram_connection`	Test Graph API connection
`debug_instagram_token`	Debug token expiry + scopes
`post_to_instagram`	Post single image (direct upload)
`test_cloudinary_upload`	Upload to Cloudinary, verify URL
`cleanup_cloudinary_asset`	Delete a Cloudinary asset
`publish_image`	Publish via Cloudinary HTTPS URL
`convert_pdf_to_images`	PDF → PNG images
`create_carousel_batch`	Group images into carousels
`post_carousel_to_instagram`	Post a carousel + auto-cleanup
`list_carousel_batches`	List carousels + status

Resource

instagram://content/{filename} — access images as base64 blobs for visual analysis.

Troubleshooting: Daily "API access blocked (code 200)"

Run test_instagram_connection and debug_instagram_token to diagnose.

Common causes & fixes:

App in Development Mode → switch to Live in Meta Developer dashboard.
Missing approved permissions → submit App Review for instagram_basic + instagram_content_publish.
Token expired/revoked (60 days) → generate a fresh long-lived token.
App flagged by Meta → check the app review status / appeal.

Logs are written to logs/instagram_mcp.log for diagnosis.

Instagram MCP Server

Instagram MCP Server

Features

Project Structure

Installation

Configuration

Running the Server

CLI Utilities

Testing

MCP Tools

Resource

Troubleshooting: Daily "API access blocked (code 200)"

Latest Blog Posts

MCP directory API