Instagram Social API MCP Server

A Model Context Protocol (MCP) server for comprehensive Instagram data analysis and content discovery using the Instagram Social API.

Features

• User Profile Analysis: Get detailed Instagram user information including stats, bio, and contact details
• Content Discovery: Retrieve user posts and reels with engagement metrics
• Post Analysis: Detailed information about specific Instagram posts, reels, and stories
• User Search: Search for Instagram users by keywords, names, or usernames
• Content Search: Search for posts and reels by keywords and hashtags
• Hashtag Analytics: Analyze hashtag performance and discover related content
• Intelligent Caching: LRU cache with TTL to optimize API usage and performance
• Error Handling: Comprehensive error handling with detailed user feedback

Installation

npm install @andrewlwn77/instagram-social-mcp

Configuration

1. Get your API key from Instagram Social API on RapidAPI

2. Set your environment variables:

# Required
INSTAGRAM_SOCIAL_API_KEY=your_rapidapi_key_here

# Optional (with defaults)
CACHE_ENABLED=true
CACHE_MAX_ENTRIES=200
CACHE_TTL_SECONDS=600

Usage

Available Tools

get_user_info

Get comprehensive Instagram user profile information.

Parameters:

• username_or_id_or_url (string): Instagram username (without @), user ID, or full profile URL

Examples:

username_or_id_or_url: "mrbeast"
username_or_id_or_url: "25025320"
username_or_id_or_url: "https://instagram.com/mrbeast"

get_user_posts

Retrieve user posts and reels with engagement metrics.

Parameters:

• username_or_id_or_url (string): User identifier
• amount (number, optional): Number of posts to retrieve (1-50, default: 12)
• end_cursor (string, optional): Pagination cursor for next set of posts

get_post_info

Get detailed information about a specific Instagram post.

Parameters:

• code_or_id_or_url (string): Post code, ID, or full post URL

Examples:

code_or_id_or_url: "CxYQJO8xuC6"
code_or_id_or_url: "https://instagram.com/p/CxYQJO8xuC6/"

search_users

Search for Instagram users by keywords.

Parameters:

• query (string): Search query for finding users
• amount (number, optional): Number of users to return (1-50, default: 20)

search_posts

Search for Instagram posts and reels by content.

Parameters:

• query (string): Search query for finding posts
• amount (number, optional): Number of posts to return (1-50, default: 20)

get_hashtag_posts

Get posts for a specific hashtag with analytics.

Parameters:

• hashtag (string): Hashtag name (without # symbol)
• amount (number, optional): Number of posts to return (1-50, default: 20)

MCP Configuration

Add to your MCP settings file (.mcp.json):

{
  "mcpServers": {
    "instagram-social-mcp": {
      "command": "npx",
      "args": ["@andrewlwn77/instagram-social-mcp"],
      "env": {
        "INSTAGRAM_SOCIAL_API_KEY": "your_rapidapi_key_here"
      }
    }
  }
}

Performance Features

Intelligent Caching

• LRU Cache: Least Recently Used eviction policy
• TTL Support: Time-based expiration (default: 10 minutes)
• Configurable: Adjust cache size and TTL via environment variables
• Automatic Cleanup: Background cleanup of expired entries

Rate Limiting Protection

• Built-in error handling for API rate limits
• Automatic retry suggestions for recoverable errors
• Cache-first approach reduces API calls

API Coverage

This MCP server implements the most valuable endpoints from the Instagram Social API:

User Profile Endpoints

• User information with contact details
• Follower/following data
• Post and reel content
• Account verification and privacy status

Content Analysis Endpoints

• Individual post details
• Engagement metrics (likes, comments, views)
• Media metadata and URLs
• Content creation timestamps

Search and Discovery

• User search by keywords
• Content search across posts and reels
• Hashtag performance analysis
• Similar account discovery

Analytics Capabilities

• Engagement rate analysis
• Content performance metrics
• Hashtag trend analysis
• Audience growth insights

Error Handling

The server provides detailed error messages for:

• Invalid API keys or authentication issues
• Rate limit exceeded scenarios
• Private or restricted content access
• Malformed requests or invalid parameters
• Network connectivity problems

Development

# Clone and install dependencies
git clone https://github.com/andrewlwn77/instagram-social-mcp.git
cd instagram-social-mcp
npm install

# Build the server
npm run build

# Development with auto-rebuild
npm run dev

# Start the server
npm start

License

MIT License - see LICENSE file for details.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

Support

• Create an issue on GitHub for bugs or feature requests
• Check the Instagram Social API documentation for API-specific questions
• Review RapidAPI dashboard for usage statistics and billing