osborn1997/instagram-mcp-server

Instagram MCP Server

An HTTP MCP (Model Context Protocol) server for interacting with Instagram and Facebook APIs. Deploy this server to any cloud platform and access it remotely via HTTPS from any MCP client.

This server enables AI assistants to send messages, view posts, manage comments, and interact with your Instagram/Facebook accounts through a REST API.

Features

Messaging

• Send text messages on Instagram and Facebook Messenger
• Send media (images, videos, audio)
• React to messages
• Human agent tag support for extended messaging windows

Inbox / Conversations

• List all conversations
• Get messages from specific conversations
• Find conversations by user ID

Profile

• Get your Instagram business profile
• Get your Facebook page info
• Look up user profiles

Posts

• View your Instagram posts and reels
• View your Facebook page posts
• Get detailed post information including carousel items

Comments

• View comments on posts
• Reply to comments

Content Creation

• Post images to Instagram
• Post videos/reels to Instagram
• Post to Facebook (text, links, photos)

Architecture

This is an HTTP-based MCP server using Express.js:

• Transport: HTTP/HTTPS (not stdio)
• Deployment: Cloud platforms (Vercel, Railway, Render, DigitalOcean, etc.)
• Access: Remote access from anywhere via HTTPS
• Authentication: API key-based (MCP_API_KEY)
• Protocol: RESTful HTTP endpoints following MCP specification

Why HTTP?

✅ Remote Access - Access from any machine, not just locally ✅ Team Sharing - Multiple team members can use the same server ✅ Scalable - Deploy to cloud platforms with auto-scaling ✅ Secure - HTTPS encryption + API key authentication ✅ Simple - Just like any REST API you're used to

Endpoints

• POST /mcp - MCP protocol endpoint (handles all tool calls)
• GET /health - Health check endpoint

Installation

cd instagram-mcp-server
npm install
npm run build

Configuration

Create a .env file based on .env.example:

cp .env.example .env

Required environment variables:

Getting Your Access Token

1. Go to Facebook Developer Portal
2. Create or select your app
3. Generate a Page Access Token with these permissions:
   • pages_messaging
   • pages_manage_metadata
   • pages_read_engagement
   • instagram_basic
   • instagram_manage_messages
   • instagram_manage_comments
   • instagram_content_publish

Running the Server

This is an HTTP MCP server that can be deployed anywhere and accessed remotely.

Local Development

# Development mode with auto-reload
npm run dev

# Production mode
npm run build
npm start

The server will start on http://localhost:3000 (or custom PORT from .env)

Endpoints:

• POST /mcp - MCP protocol endpoint
• GET /health - Health check endpoint

Test the Server

# Health check
curl http://localhost:3000/health

# List available tools
curl -X POST http://localhost:3000/mcp \
  -H "Authorization: Bearer my-secret-api-key-12345" \
  -H "Content-Type: application/json" \
  -d '{"method": "tools/list"}'

Connecting MCP Clients

Claude Code

Add the server to Claude Code using the CLI:

# For production (deployed server)
claude mcp add-json --scope user instagram '{
  "type": "http",
  "url": "https://your-domain.com/mcp",
  "headers": {
    "Authorization": "Bearer your-mcp-api-key"
  }
}'

# For local testing
claude mcp add-json --scope user instagram '{
  "type": "http",
  "url": "http://localhost:3000/mcp",
  "headers": {
    "Authorization": "Bearer my-secret-api-key-12345"
  }
}'

Other MCP Clients

Any MCP-compatible client can connect via HTTP:

const response = await fetch('https://your-domain.com/mcp', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer your-mcp-api-key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    method: 'tools/call',
    params: {
      name: 'send_message',
      arguments: {
        platform: 'instagram',
        recipientId: '123456',
        text: 'Hello!'
      }
    }
  })
});

Available Tools

Messaging

• send_message - Send text/media message to Instagram or Facebook
• send_reaction - React to a message

Conversations

• get_conversations - List inbox conversations
• get_conversation_by_user - Find conversation by user ID
• get_conversation_messages - Get messages from a conversation

Profiles

• get_user_profile - Get a user's profile
• get_my_instagram_profile - Get your IG profile
• get_my_facebook_page - Get your FB page info

Posts

• get_posts - List your posts
• get_instagram_post_details - Get detailed post info

Comments

• get_post_comments - Get comments on a post
• reply_to_comment - Reply to a comment

Content Creation

• post_to_instagram - Create Instagram post/reel
• post_to_facebook - Create Facebook post

Available Resources

The server also exposes these resources for easy access:

• instagram://profile - Your Instagram profile
• facebook://page - Your Facebook page
• instagram://inbox - Instagram DM inbox
• facebook://inbox - Facebook Messenger inbox
• instagram://posts - Recent Instagram posts
• facebook://posts - Recent Facebook posts

Development

# Run in development mode (auto-reload)
npm run dev

# Build for production
npm run build

# Run production build
npm start

Note: A stdio version is also available for local-only use. Run with npm run dev:stdio or npm run start:stdio

Deployment

Deploy to Vercel

1. Install Vercel CLI:

npm i -g vercel

2. Create vercel.json:

{
  "version": 2,
  "builds": [{
    "src": "dist/index.js",
    "use": "@vercel/node"
  }],
  "routes": [{
    "src": "/(.*)",
    "dest": "/dist/index.js"
  }],
  "env": {
    "FB_PAGE_ID": "@fb_page_id",
    "IG_ACCOUNT_ID": "@ig_account_id",
    "FB_PAGE_ACCESS_TOKEN": "@fb_page_access_token",
    "FB_API_VERSION": "v24.0",
    "MCP_API_KEY": "@mcp_api_key"
  }
}

3. Deploy:

npm run build
vercel --prod

4. Set environment variables in Vercel dashboard

Deploy to Railway

1. Create railway.toml:

[build]
builder = "NIXPACKS"
buildCommand = "npm install && npm run build"

[deploy]
startCommand = "npm start"
restartPolicyType = "ON_FAILURE"
restartPolicyMaxRetries = 10

2. Deploy:

# Install Railway CLI
npm i -g @railway/cli

# Login and deploy
railway login
railway init
railway up

3. Set environment variables in Railway dashboard

Deploy to Render

1. Create account at https://render.com

2. Create new Web Service

3. Configure:

   • Build Command: npm install && npm run build
   • Start Command: npm start
   • Add environment variables

Deploy to DigitalOcean/VPS

# SSH into your server
ssh user@your-server

# Clone repo
git clone https://github.com/yourusername/instagram-mcp-server.git
cd instagram-mcp-server

# Install dependencies and build
npm install
npm run build

# Create .env file with your credentials
nano .env

# Run with PM2 for process management
npm install -g pm2
pm2 start npm --name "instagram-mcp" -- start
pm2 save
pm2 startup

Environment Variables for Production

Required:

• FB_PAGE_ID - Your Facebook Page ID
• FB_PAGE_ACCESS_TOKEN - Page Access Token
• IG_ACCOUNT_ID - Instagram Business Account ID
• FB_API_VERSION - Graph API version (default: v24.0)
• MCP_API_KEY - Secret key for MCP endpoint authentication
• PORT - Server port (default: 3000)

Security Notes

⚠️ IMPORTANT: When deploying publicly:

1. Always set MCP_API_KEY - Never deploy without authentication
2. Use HTTPS only - Encrypt all traffic
3. Rotate tokens regularly - Update access tokens periodically
4. Use environment variables - Never commit secrets to git
5. Rate limiting - Consider adding rate limiting for production

License

MIT