Instagram MCP Server

A Model Context Protocol (MCP) server for fetching Instagram posts using Chrome's existing login session.

Features

- Modular architecture with clear separation of concerns
- Type-safe implementation using TypeScript
- Improved error handling and logging
- Configurable through environment variables
- JSON-RPC 2.0 compliant communication
- Automatic media downloading and metadata generation
- SEO-friendly description generation

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         # Barrel exports
│   ├── types/               # Core type definitions
│   │   └── mcp.ts          # MCP types
│   └── utils/               # Utility functions
│       ├── config.ts        # Configuration management
│       └── errors.ts        # Error handling
├── features/                 # Feature modules
│   └── instagram/           # Instagram feature
│       ├── types.ts         # Instagram types
│       ├── utils/           # Feature utilities
│       │   ├── media.ts     # Media handling
│       │   ├── post.ts      # Post processing
│       │   └── 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: Path to Chrome user data directory containing login session

Additional configuration options are available through the config manager:

- Browser settings (viewport, timeouts)
- Instagram settings (delays, batch sizes)
- Save directory and file paths

Usage

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

   

Available Tools

get_instagram_posts

Fetches recent posts from an Instagram profile.

Parameters:
- username (required): Instagram username to fetch posts from
- limit (optional): Number of posts to fetch (1-50) or "all"
- saveDir (optional): Directory to save media files and metadata
- delayBetweenPosts (optional): Milliseconds to wait between processing posts

Example:

{

  "jsonrpc": "2.0",

  "id": 1,

  "method": "call_tool",

  "params": {

    "name": "get_instagram_posts",

    "arguments": {

      "username": "example",

      "limit": 10

    }

  }

}

Error Handling

The server uses standardized error codes and messages:

- INVALID_REQUEST: Invalid request format or parameters
- INVALID_PARAMS: Missing or invalid parameters
- METHOD_NOT_FOUND: Unknown method or tool
- INTERNAL_ERROR: Server-side errors

Development

1. Start in development mode:

   npm run dev

   

2. Run linter:

   npm run lint

   

Improvements Over Original

1. Modular Architecture
- Clear separation of concerns
- Better code organization
- Easier to maintain and extend

2. Type Safety
- Comprehensive TypeScript types
- Better error catching
- Improved IDE support

3. Error Handling
- Standardized error codes
- Better error messages
- Proper error propagation

4. Configuration
- Centralized configuration
- Environment variable validation
- Type-safe config access

5. Code Quality
- Consistent coding style
- Better documentation
- Improved logging

6. Testing Support
- Modular design enables testing
- Dependency injection ready
- Clear interfaces

License

MIT