Instagram MCP Server
Provides image hosting via Cloudinary for temporary storage and auto-cleanup when publishing to Instagram.
Provides tools for managing and posting Instagram content, including single image and carousel posts via the Instagram Graph API.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Instagram MCP Server Convert the product PDF to carousel images and post it"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 configInstallation
# 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=falseRunning 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-mcpCLI 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.pyTesting
pip install -e ".[dev]"
pytestMCP Tools
Tool | Purpose |
| List local images in content dir |
| Get file metadata (mime, size) |
| list / delete / archive content |
| Update / view / clear captions & hashtags |
| Test Graph API connection |
| Debug token expiry + scopes |
| Post single image (direct upload) |
| Upload to Cloudinary, verify URL |
| Delete a Cloudinary asset |
| Publish via Cloudinary HTTPS URL |
| PDF ā PNG images |
| Group images into carousels |
| Post a carousel + auto-cleanup |
| 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.
Available Tools
14 toolscleanup_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).
create_carousel_batchA
Create carousel batches from selected images or PDF pages.
Parameters:
content_ids: Comma-separated list of content IDs (e.g., "image1,image2,image3,image4,image5,image6,image7,image8,image9,image10")
batch_name: Optional name for this batch (e.g., "Q1_Report" or "pdf_name")
images_per_post: How many images per carousel post (default: 5, max: 10 for Instagram)
Example: 10 images with images_per_post=5 creates 2 carousel batches
Inputs: content_ids (required), batch_name, images_per_post.
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_carousel_batchesA
List all carousel batches and their status.
Shows each batch ID, posted status, image count, and batch progression.
Inputs: no named parameters.
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
Scored across 14 tools
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.
All tool names consistently use snake_case with a verb_noun or verb_to_noun pattern, creating a predictable and clear naming convention.
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.
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
A hosted MCP server for planning, scheduling, media, analytics, and social publishing.
Hosted Instagram MCP server for Claude, ChatGPT and Cursor, with each action switched per account.
MCP server for QPost ā lets AI agents publish video and image posts to YouTube, TikTok, Instagram.
Hosted MCP for Instagram, Facebook, X, LinkedIn, Pinterest, and Ghost. OAuth 2.1, 38 tools.
Related MCP Servers
- AlicenseAqualityDmaintenanceInstagram MCP server with 23 tools for the Graph API. Manage posts, comments, DMs, stories, hashtags, reels, carousels, and analytics.2378MIT
- AlicenseNot gradedqualityCmaintenanceMCP server providing seamless integration with Instagram's Graph API for business account management, content publishing, and analytics.MIT
- AlicenseNot gradedqualityDmaintenanceMCP server for Instagram Graph API providing 25 tools for publishing photos, reels, carousels, and stories, managing comments, viewing insights, and searching hashtags.13 npm1MIT
- AlicenseNot gradedqualityDmaintenanceA self-hosted MCP server for managing Instagram and Facebook Page content, including posting, scheduling, analytics, and autopilot features.1GPL 3.0