Skip to main content
Glama
Instagram MCP Server

Instagram MCP Server

by anas7272

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

Related MCP server: instagram-mcp

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.

Available Tools

14 tools
cleanup_cloudinary_assetB

Delete a temporary Cloudinary asset manually.

Inputs: public_id (required).

convert_pdf_to_imagesA

Convert a PDF file to individual PNG images.

Each page becomes a separate image. Images are stored in the content folder with the PDF name as prefix.

Example: document.pdf -> document_page_001.png, document_page_002.png, etc.

Inputs: filename (required).

debug_instagram_tokenA

Inspect the configured Instagram access token via Meta's debug_token endpoint.

Reports the token's type, expiry date, and granted scopes. Use this to determine whether the token is expired, about to expire, or lacks the required permissions (instagram_basic, instagram_content_publish).

Inputs: no named parameters.

get_contentA

Safely locate a local content file and return basic metadata.

Inputs: filename (required).

list_contentA

List available local images in the content directory.

Inputs: no named parameters.

manage_contentB

Manage Instagram content stored in the content folder.

Actions:

  • list: Show all available content with metadata

  • delete: Permanently delete selected content

  • archive: Move selected content to archive folder

Inputs: action, content_id.

manage_metadataC

Manage metadata for Instagram content (captions, hashtags, scheduling).

Actions:

  • update: Update caption and/or hashtags

  • view: View current metadata

  • clear: Clear caption and hashtags

Inputs: content_id (required), action, caption, hashtags.

post_carousel_to_instagramA

Post a carousel batch to Instagram.

Uploads all images in the batch to Cloudinary, creates a CAROUSEL media container via the Instagram Graph API, publishes it, then deletes the local images and Cloudinary temporary assets.

Requires 2-10 images per carousel (Instagram limit).

Inputs: batch_id (required).

post_to_instagramC

Post content to Instagram using Instagram Graph API.

Prerequisites:

  • Set INSTAGRAM_ACCESS_TOKEN environment variable

  • Set INSTAGRAM_BUSINESS_ACCOUNT_ID environment variable

  • Instagram access token must have appropriate permissions

Inputs: content_id (required).

publish_imageC

Publish a local image to Instagram using a Cloudinary-hosted HTTPS image URL.

Inputs: caption (required), filename (required).

test_cloudinary_uploadA

Upload a local image to Cloudinary without posting to Instagram.

Inputs: filename (required).

test_instagram_connectionA

Test the Instagram Graph API connection and report the exact status.

Use this first whenever posting fails, to determine whether the problem is:

  • Expired/revoked token (code 190 or 200, type OAuthException)

  • Missing permissions (code 10)

  • Rate limiting (code 4 or 32)

  • API version deprecated (code 100)

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 14 tools

    Disambiguation3/5

    Several tools overlap in function: list_content and manage_content's list action both list content, and post_to_instagram and publish_image both post to Instagram via different paths. Descriptions help but the boundaries could still confuse an agent.

    Naming Consistency5/5

    All tool names consistently use snake_case with a verb_noun or verb_to_noun pattern, creating a predictable and clear naming convention.

    Tool Count5/5

    14 tools is well within the ideal 3-15 range for an Instagram content server, covering posting, content management, metadata, diagnostics, and carousel workflows without feeling bloated.

    Completeness3/5

    Core posting and content management workflows are covered, but there are notable gaps: no post deletion or status retrieval, and scheduling is mentioned in manage_metadata but not actually implemented as a tool.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      MCP server providing seamless integration with Instagram's Graph API for business account management, content publishing, and analytics.
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server for Instagram Graph API providing 25 tools for publishing photos, reels, carousels, and stories, managing comments, viewing insights, and searching hashtags.
      13 npm
      1
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      A self-hosted MCP server for managing Instagram and Facebook Page content, including posting, scheduling, analytics, and autopilot features.
      1
      GPL 3.0