8000 GitHub - sonfu4u/ig-mcp: provides secure Instagram management · GitHub
[go: up one dir, main page]

Skip to content
sonfu4uPublic

About

provides secure Instagram management

Resources

Stars

0 stars

Watchers

0 watching

Forks

 
 

Repository files navigation

Instagram MCP Server

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.

Features

  • 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

Prerequisites

  • Python 3.10 or higher
  • Instagram App credentials (App ID and Secret)
  • Professional or Business Instagram account

Installation

  1. Clone the repository and navigate to the project directory:
git clone https://github.com/SkillShopPro/ig-mcp.git
cd ig-mcp
  1. Create a virtual environment:
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
  1. Install dependencies:
pip install -r requirements.txt
  1. Copy .env.example to .env and configure:
cp .env.example .env

Configuration

Instagram App Setup

  1. Go to Meta for Developers
  2. Create a new app or select existing one
  3. Add Instagram product to your app
  4. Configure Instagram Business Login
  5. Add your redirect URI: http://localhost:8888/callback
  6. Copy your App ID and App Secret

Environment Variables

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_here

Usage

Starting the Server

Run the MCP server:

python -m src.server

Or use the npm script:

npm run dev

Available Tools

Authentication Tools

  • 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

Profile Tools

  • instagram_get_profile: Get user profile information
    {
      "account_id": "optional_account_id"
    }

Media Tools

  • 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"
    }

Analytics Tools

  • 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"
    }

Comment Tools

  • 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"
    }

Using with Claude

  1. Configure Claude to use this MCP server
  2. Start the server
  3. 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"

Security

  • 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

Troubleshooting

Common Issues

  1. "No token found": Run instagram_get_auth_url to authenticate
  2. "Token expired": Run instagram_refresh_token to refresh
  3. "API error": Check if your account has necessary permissions
  4. OAuth callback fails: Ensure redirect URI matches exactly

Debug Mode

Enable debug logging by setting:

LOG_LEVEL=DEBUG

Development

Running Tests

pytest

Code Formatting

ruff format .

Linting

ruff check .

License

MIT License - see LICENSE file for details

Support

For issues and feature requests, please open an iss 4C3A ue in the repository.

About

provides secure Instagram management

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages

0