# 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
```bash
cd instagram-mcp-server
npm install
npm run build
```
## Configuration
Create a `.env` file based on `.env.example`:
```bash
cp .env.example .env
```
Required environment variables:
| Variable | Description |
|----------|-------------|
| `FB_PAGE_ID` | Your Facebook Page ID |
| `FB_PAGE_ACCESS_TOKEN` | Page Access Token with required permissions |
| `IG_ACCOUNT_ID` | (Optional) Instagram Business Account ID |
| `FB_API_VERSION` | (Optional) Graph API version (default: v24.0) |
### Getting Your Access Token
1. Go to [Facebook Developer Portal](https://developers.facebook.com)
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
```bash
# 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
```bash
# 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:
```bash
# 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:
```javascript
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
```bash
# 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:
```bash
npm i -g vercel
```
2. Create `vercel.json`:
```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:
```bash
npm run build
vercel --prod
```
4. Set environment variables in Vercel dashboard
### Deploy to Railway
1. Create `railway.toml`:
```toml
[build]
builder = "NIXPACKS"
buildCommand = "npm install && npm run build"
[deploy]
startCommand = "npm start"
restartPolicyType = "ON_FAILURE"
restartPolicyMaxRetries = 10
```
2. Deploy:
```bash
# 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
```bash
# 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
