Instagram Server Next MCP

🚀 Instagram MCP Server

An MCP (Model Context Protocol) server that uses an existing Chrome login session to scrape Instagram posts.

🚀 Quick Start

To get started with the Instagram MCP Server, follow these steps:

1. Install dependencies:

   npm install
   

2. Build the server:

   npm run build
   

3. Run the server:

   CHROME_USER_DATA_DIR=/path/to/chrome/profile npm start
   

✨ Features

• Modular architecture: Clear separation of concerns.
• Type safety: Implemented in TypeScript.
• Enhanced error handling and logging: Improved error management and logging.
• Configuration via environment variables: Easy to configure.
• Compliance with JSON - RPC 2.0: Follows the JSON - RPC 2.0 communication protocol.
• Automated media download and metadata generation: Automatically download media files and generate metadata.
• SEO - friendly descriptions: Create SEO - friendly descriptions.

🔧 Technical Details

Architecture

The server follows a modular architecture with the following structure:

src/
├── core/                      # Core MCP functionality
│   ├── mcp/                  # MCP server implementation
│   │   ├── server.ts        # Server class
│   │   ├── stdio.ts         # StdioServerTransport
│   │   └── index.ts         # Export barrel
│   ├── types/               # Core type definitions
│   │   └── mcp.ts          # MCP types
│   └── utils/               # Utility functions
│       ├── config.ts        # Configuration management
│       └── errors.ts        # Error handling
├── features/                 # Feature modules
│   └── instagram/           # Instagram features
│       ├── types.ts         # Instagram types
│       ├── utils/           # Feature utilities
│       │   ├── media.ts     # Media handling
│       │   ├── post.ts      # Post handling
│       │   └── seo.ts       # SEO generation
│       └── instagram.service.ts # Instagram service
├── services/                 # Shared services
│   └── browser/             # Browser service
│       ├── types.ts         # Browser types
│       └── browser.service.ts # Browser service
├── index.ts                 # Entry point
└── server.ts                # Main server class

Configuration

The server requires the following environment variables:

• CHROME_USER_DATA_DIR: The path to the Chrome user data directory containing the login session.

In addition, there are other configuration options available through the configuration manager:

• Browser settings: Viewport, timeout.
• Instagram settings: Delay, batch size.
• Save directories and file paths.

💻 Usage Examples

get_instagram_posts

Scrape recent posts from an Instagram profile.

Parameters:

• username (required): The Instagram username to scrape.
• limit (optional): The number of posts to scrape (1 - 50) or "all".
• saveDir (optional): The directory to save media files and metadata.
• delayBetweenPosts (optional): The waiting time between processing posts (in milliseconds).

Example:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "call_tool",
  "params": {
    "name": "get_instagram_posts",
    "arguments": {
      "username": "example",
      "limit": 10
    }
  }
}

Example Output

$ npm start -- get_instagram_posts --username example --limit 10

Output:

{
  "status": "success",
  "result": {
    "posts": [
      {
        "id": "post_id_1",
        "url": "https://www.instagram.com/post/1234567890/",
        "username": "example",
        "caption": "This is an example post.",
        "likes": 123,
        "comments": 45
      },
      // Other posts...
    ]
  }
}

📚 Documentation

Error Handling

The server uses standardized error codes and messages:

• ERR_NO_API_KEY: API key not set.
• ERR_INVALID_ARGUMENT: Invalid argument.
• ERR_DATABASE_ERROR: Database error.
• ERR_AUTHENTICATION_FAILED: Authentication failed.
• ERR_NETWORK: Network issue.

Exit Status

The server returns the following exit statuses:

• 0: Success.
• 1: General error.
• 2: Configuration error.
• 3: Authentication error.
• 4: Database error.
• 5: Network error.

📄 License

No license information provided in the original document.

⚠️ Important Note

• Make sure Node.js and npm are installed.
• The configuration file may contain sensitive information and should be kept secure.
• When handling large amounts of data, it is recommended to enable pagination.