A Model Context Protocol (MCP) server for managing Instagram accounts, built with FastMCP. This server provides tools for Instagram authentication, content management, and analytics through a secure OAuth flow.
- OAuth Authentication: Secure Instagram login with automatic token management
- Profile Management: Get user profile information and statistics
- Content Operations: List, view, and publish posts
- Analytics: Access post and account insights
- Comment Management: View and reply to comments
- Multi-Account Support: Manage multiple Instagram accounts
- Secure Token Storage: Encrypted token storage with automatic refresh
- Python 3.10 or higher
- Instagram App credentials (App ID and Secret)
- Professional or Business Instagram account
- Clone the repository and navigate to the project directory:
git clone https://github.com/SkillShopPro/ig-mcp.git
cd ig-mcp- Create a virtual environment:
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate- Install dependencies:
pip install -r requirements.txt- Copy
.env.exampleto.envand configure:
cp .env.example .env- Go to Meta for Developers
- Create a new app or select existing one
- Add Instagram product to your app
- Configure Instagram Business Login
- Add your redirect URI:
http://localhost:8888/callback - Copy your App ID and App Secret
Edit your .env file with your Instagram app credentials:
# Instagram App Configuration
INSTAGRAM_APP_ID=your_app_id_here
INSTAGRAM_APP_SECRET=your_app_secret_here
INSTAGRAM_REDIRECT_URI=http://localhost:8888/callback
INSTAGRAM_SCOPES=instagram_business_basic,instagram_business_content_publish,instagram_business_manage_comments,instagram_business_manage_messages
# Security
TOKEN_ENCRYPTION_KEY=generate_a_secure_random_key_hereRun the MCP server:
python -m src.serverOr use the npm script:
npm run dev-
instagram_get_auth_url: Generate OAuth URL and start authentication
{ "open_browser": true // Automatically open browser } -
instagram_exchange_code: Complete OAuth flow and get access token
{ "code": "authorization_code", // Optional, waits for callback if not provided "wait_for_callback": true, "exchange_for_long_lived": true } -
instagram_refresh_token: Refresh access token before expiration
{ "account_id": "optional_account_id" } -
instagram_logout: Remove stored authentication
{ "account_id": "optional_account_id" } -
instagram_list_accounts: List all authenticated accounts
- instagram_get_profile: Get user profile information
{ "account_id": "optional_account_id" }
-
instagram_list_media: List user's posts
{ "limit": 10, "after": "pagination_cursor", "account_id": "optional_account_id" } -
instagram_get_media_details: Get detailed post information
{ "media_id": "instagram_media_id", "account_id": "optional_account_id" } -
instagram_publish_post: Create a new post
{ "image_url": "https://example.com/image.jpg", "caption": "Post caption", "location_id": "optional_location_id", "account_id": "optional_account_id" }
-
instagram_get_media_insights: Get post analytics
{ "media_id": "instagram_media_id", "metrics": ["impressions", "reach", "engagement"], "account_id": "optional_account_id" } -
instagram_get_account_insights: Get account analytics
{ "metrics": ["impressions", "reach", "profile_views"], "period": "day", "since": "2024-01-01", "until": "2024-01-31", "account_id": "optional_account_id" }
-
instagram_get_media_comments: Get post comments
{ "media_id": "instagram_media_id", "limit": 10, "after": "pagination_cursor", "account_id": "optional_account_id" } -
instagram_reply_to_comment: Reply to a comment
{ "comment_id": "instagram_comment_id", "message": "Reply text", "account_id": "optional_account_id" }
- Configure Claude to use this MCP server
- Start the server
- In Claude, use natural language to interact:
- "Connect my Instagram account"
- "Show my recent posts"
- "Get analytics for my last post"
- "Publish a new post with this image"
- Tokens are encrypted using Fernet symmetric encryption
- Encryption keys are derived from environment variables
- Token files are stored with restricted permissions (600)
- OAuth state parameter prevents CSRF attacks
- "No token found": Run
instagram_get_auth_urlto authenticate - "Token expired": Run
instagram_refresh_tokento refresh - "API error": Check if your account has necessary permissions
- OAuth callback fails: Ensure redirect URI matches exactly
Enable debug logging by setting:
LOG_LEVEL=DEBUGpytestruff format .ruff check .MIT License - see LICENSE file for details
For issues and feature requests, please open an iss 4C3A ue in the repository.