Instagram MCP Server

This MCP (Model Content Protocol) server provides access to Instagram API functionality through STDIO transport mode with FastMCP.

Features

FastMCP-based server with decorator pattern
Automatic tool registration via @mcp.tool() decorators
Type-safe parameter handling
Comprehensive error handling and logging
Easy configuration through environment variables

Prerequisites

Python 3.10 or later
pip package manager

Installation

Install dependencies:

pip install -r requirements.txt

Configure environment variables:

export API_BASE_URL="https://your-api-base-url"
export BEARER_TOKEN="your-bearer-token"
# Alternative authentication options (use only one):
# export API_KEY="your-api-key"
# export BASIC_AUTH="your-basic-auth-credentials"

Running the MCP Server

STDIO Mode (Default)

The server runs in STDIO mode by default, which is perfect for direct integration with AI assistants like Cursor:

python main.py

Configuration for Cursor/Claude Desktop

Add this to your MCP configuration file (e.g., ~/Library/Application Support/Cursor/User/globalStorage/@anthropic/mcp-server-registry/mcp.json):

{
  "mcpServers": {
    "instagram-mcp-server": {
      "command": "python",
      "args": ["/path/to/your/project/main.py"],
      "env": {
        "API_BASE_URL": "https://your-api-base-url",
        "BEARER_TOKEN": "your-bearer-token"
      }
    }
  }
}

Environment Variables

Required

API_BASE_URL: Base URL for the API endpoint

Authentication (use one of the following)

BEARER_TOKEN: Bearer token for OAuth2/Bearer authentication
API_KEY: API key for API key authentication
BASIC_AUTH: Basic authentication credentials (base64 encoded)

Note: At least one authentication variable should be provided unless the API explicitly doesn't require authentication.

Development

For development with auto-reload:

# Install development dependencies
pip install -r requirements.txt

# Run with Python
python main.py

Project Structure

.
├── main.py              # Entry point with FastMCP server
├── config.py            # Configuration management
├── models.py            # Pydantic data models
├── tools/               # Auto-generated tools organized by category
│   ├── __init__.py
│   └── [category]/      # Tools grouped by API endpoint category
│       ├── __init__.py
│       └── *.py         # Individual tool implementations
├── requirements.txt     # Python dependencies
└── README.md           # This file

How It Works

This MCP server is built using FastMCP with a decorator-based architecture:

FastMCP Server: Creates an MCP server instance in main.py
Tool Decorators: Each tool is decorated with @mcp.tool() for automatic registration
Auto-Import: Tools are automatically registered when their modules are imported
Type Safety: Uses Python type hints for parameter validation
Error Handling: Comprehensive error handling with JSON error responses

Example Tool

from main import mcp

@mcp.tool()
def get_users(search: str = None, page: int = None) -> str:
    """
    Get users from the API.
    
    Args:
        search: Search query for filtering users
        page: Page number for pagination
        
    Returns:
        JSON string with user data
    """
    # Tool implementation...
    return json.dumps(result, indent=2)

Authentication Methods

The server supports multiple authentication methods:

Bearer Token (OAuth2)

export BEARER_TOKEN="your-bearer-token"

API Key

export API_KEY="your-api-key"

Basic Authentication

export BASIC_AUTH="base64-encoded-credentials"

Logging

The server includes comprehensive logging to stderr:

INFO level: General operations, tool registration
WARNING level: Skipped operations, missing parameters
ERROR level: API errors, request failures

View logs in your MCP client's console or stderr output.

Troubleshooting

"Missing required parameter" errors

Check that all required parameters are provided
Verify parameter names match the tool definition

Authentication errors

Ensure the correct authentication environment variable is set
Verify your credentials are valid and not expired
Check that the API_BASE_URL is correct

Import errors

Run pip install -r requirements.txt to ensure all dependencies are installed
Check that you're using Python 3.10 or later

Tool not found

Verify the tool name matches what's shown in your MCP client
Check the tools directory structure
Ensure all __init__.py files are present

Generated Tools

This server was automatically generated from an OpenAPI specification. Each API endpoint is exposed as an MCP tool with:

Automatic parameter extraction and validation
Type-safe parameter handling
Comprehensive error handling
JSON response formatting

Use your MCP client's tool listing feature to see all available tools.

Contributing

This is a generated MCP server. To modify tool behavior:

Edit the tool implementation in tools/[category]/[tool_name].py
Maintain the @mcp.tool() decorator for registration
Keep the function signature for parameter validation
Test changes by running the server locally

License

This generated MCP server follows the same license as the generator tool.