instagram server next mcp

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
2. Clear separation of concerns
3. Better code organization

4. Easier to maintain and extend

5. Type Safety

6. Comprehensive TypeScript types
7. Better error catching

8. Improved IDE support

9. Error Handling

10. Standardized error codes
11. Better error messages

12. Proper error propagation

13. Configuration

14. Centralized configuration
15. Environment variable validation

16. Type-safe config access

17. Code Quality

18. Consistent coding style
19. Better documentation

20. Improved logging

21. Testing Support

22. Modular design enables testing
23. Dependency injection ready
24. Clear interfaces

License

MIT