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:

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

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