Overview

This MCP (Model Context Protocol) server provides a bridge between large language models and Instagram Direct Messages, allowing an LLM to send, route, and manage Instagram DMs programmatically. Instead of embedding Instagram credentials into every LLM prompt, the server exposes a small set of verifiable tools (MCP endpoints) that the LLM can call to perform messaging actions. The server handles authentication, rate limiting, retries, and delivery tracking so the LLM can focus on decision-making.

For developers building AI agents, chatbots, or automation pipelines, the server enables safe, auditable, and scalable DM delivery. It centralizes account configuration and security controls (session tokens, API keys, access policies), and can be deployed locally or in containerized environments for production use.

Features

Exposes MCP-compliant tools for Instagram messaging (send text, send media, fetch thread/status)
Centralized account/session management (support for session cookies or long-lived tokens)
Delivery tracking, retry logic, and rate limiting to avoid Instagram throttling
Request queuing and worker processing for scale
Authentication and audit logs for secure operations
Docker-ready and easy local setup for development

Installation / Configuration

Prerequisites:

Node.js 18+ or Docker
An Instagram session token / cookie (recommended over username/password)
(Optional) PostgreSQL or Redis for queuing and persistent state

Quick start — clone and run locally (Node):

git clone https://github.com/trypeggy/instagram_dm_mcp.git
cd instagram_dm_mcp
# install dependencies
npm install
# create .env file (example below), then
npm run start

Example .env (required fields):

# Server
MCP_PORT=3000
AUTH_TOKEN=replace_with_secure_token

# Instagram session (recommended)
IG_SESSION_COOKIE=YOUR_IG_SESSION_COOKIE

# Optional DB / queue
DATABASE_URL=postgres://user:pass@localhost:5432/insta_mcp
REDIS_URL=redis://localhost:6379

# Rate limiting
RATE_LIMIT_PER_MINUTE=60
LOG_LEVEL=info

Quick start — Docker:

# docker-compose.yml (example)
version: "3.8"
services:
  instagram-mcp:
    image: ghcr.io/trypeggy/instagram_dm_mcp:latest
    ports:
      - "3000:3000"
    environment:
      - MCP_PORT=3000
      - AUTH_TOKEN=${AUTH_TOKEN}
      - IG_SESSION_COOKIE=${IG_SESSION_COOKIE}
      - RATE_LIMIT_PER_MINUTE=60
    restart: unless-stopped

Start:

docker compose up -d

Available Tools

The server exposes a small toolbox the LLM can call via MCP. Tools are documented with names, input schemas, and example responses.

send_dm: Send a text DM to a username or user ID
send_media: Upload and send an image/video with caption
get_thread: Retrieve messages and metadata for a conversation
check_delivery: Check delivery/read status for a message
list_accounts: List configured Instagram accounts available to the MCP server

Example tool schema (JSON-style):

{
  "name": "send_dm",
  "description": "Send a text message to an Instagram user.",
  "input": {
    "recipient": "string (username or user_id)",
    "message": "string",
    "account_id": "string (optional)"
  },
  "output": {
    "message_id": "string",
    "status": "queued | sent | failed",
    "details": "object"
  }
}

Example tool call (HTTP):

curl -X POST "http://localhost:3000/mcp/send_dm" \
  -H "Authorization: Bearer ${AUTH_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"recipient":"jane_doe","message":"Hello from the LLM!"}'

Example response:

{
  "message_id": "msg_12345",
  "status": "queued",
  "details": {"eta_seconds": 2}
}

Use Cases

Agent-driven customer support: An LLM can triage incoming queries and call send_dm to respond on behalf of an agent account while the server logs each action for audits.
Notification and alerts: Services can use the MCP server to push time-sensitive notifications to users on Instagram without exposing account credentials to multiple services.
Marketing / outreach workflows: Coordinate scheduled, rate-limited outreach campaigns with queuing and retry logic to avoid account blocks.
Moderation and abuse handling: Automate warning messages or escalation steps when LLMs detect policy violations in conversations.
Human-in-the-loop workflows: Route complex conversations to a human operator while automated replies handle routine inquiries.

Resources

GitHub repository: https://github.com/trypeggy/instagram_dm_mcp
Recommended deployment: Docker + managed Redis/Postgres for queues and persistence
Security tips:
- Use long-lived session cookies rather than raw passwords
- Rotate AUTH_TOKEN and restrict access to the MCP endpoints via network policies
- Log all tool calls for auditability and rate-limit per account to prevent Instagram throttling

If you’re integrating an LLM agent, configure the model to call these MCP tools instead of injecting credentials into prompts. This keeps your automation secure, traceable, and easier to scale.

Instagram DM MCP Server for LLMs