instagram-claude-mcp

Remote MCP server that connects Claude to the official Meta Instagram Graph API (read-only).

Exposes Instagram profile, media, insights, and comments as MCP tools over Streamable HTTP, so Claude can call them via an HTTPS MCP URL.

Features

Not implemented (by design): publishing, deleting, messaging, comment replies, or any write operations.

Related MCP server: instagram-mcp

Requirements

• Node.js 20+

• An Instagram professional account (Business or Creator)

• A Meta app with Instagram Graph API access

• A long-lived access token with read permissions for the account

• The Instagram account ID (IG User ID)

Environment variables

Copy .env.example to .env and fill in values locally. Never commit .env.

Local development

npm install
cp .env.example .env
# Edit .env with INSTAGRAM_ACCESS_TOKEN and INSTAGRAM_ACCOUNT_ID

npm run dev
# or
npm run build && npm start

Endpoints:

• Health: GET http://localhost:3000/health

• Auth debug (safe): GET http://localhost:3000/debug-instagram-auth

• Profile tool debug: GET http://localhost:3000/debug-instagram-profile

• Media list debug: GET http://localhost:3000/debug-instagram-media

• MCP (Streamable HTTP): http://localhost:3000/mcp

Instagram Login id vs user_id

On graph.instagram.com, GET /me returns:

• id — app-scoped ID (not used for /media)

• user_id — Instagram professional account ID (<IG_ID>) used for /{user_id}/media, insights, etc.

This server resolves user_id from /me for Instagram Login and does not blindly trust INSTAGRAM_ACCOUNT_ID (which is often mistakenly set to id).

Instagram Login tokens (short vs long-lived)

• App Dashboard → Generate token: already long-lived (~60 days). Put it in INSTAGRAM_ACCESS_TOKEN.

• OAuth / Business Login (authorization code → token): returns a short-lived token (~1 hour). Exchange it before production use:

  1. Set INSTAGRAM_ACCESS_TOKEN to the short-lived token (temporarily).

  2. Set INSTAGRAM_APP_SECRET to your Instagram app secret.

  3. POST /exchange-instagram-token (send Authorization: Bearer <MCP_AUTH_TOKEN> if configured).

  4. Copy long_lived_access_token from the JSON into INSTAGRAM_ACCESS_TOKEN on Vercel.

  5. Redeploy / restart. Remove the short-lived value.

Auth is sent as Meta’s documented access_token query parameter. Tokens are trimmed (whitespace, quotes, accidental Bearer / access_token= prefixes) before use. The full token is never logged or returned by /debug-instagram-auth.

Type-check without running:

npm run typecheck

Test with MCP Inspector

npx @modelcontextprotocol/inspector

Connect with transport Streamable HTTP and URL http://localhost:3000/mcp.

Deploy as a remote MCP server

Vercel (serverless Express)

This project is set up for Vercel’s Express runtime: the app is exported as a default Express handler and only calls app.listen() when not running on Vercel (VERCEL=1). That matches serverless invocation — there is no permanently running Node process in production.

1. Import the GitHub repo in Vercel (or run vercel).

2. Set Project Environment Variables (Production/Preview):

   • INSTAGRAM_ACCESS_TOKEN

   • INSTAGRAM_ACCOUNT_ID

   • Optional: MCP_AUTH_TOKEN, INSTAGRAM_GRAPH_API_BASE, INSTAGRAM_API_VERSION

3. Deploy. Endpoints stay the same:

   • https://your-app.vercel.app/health

   • https://your-app.vercel.app/mcp (Streamable HTTP)

vercel.json pins the Express framework, runs npm run build, and sets function maxDuration to 60s for Graph API calls. MCP handling is stateless (fresh transport per request), which is compatible with Vercel Functions / Fluid compute.

Claude connector URL example:

https://your-app.vercel.app/mcp

Other Node hosts (Railway, Render, Fly.io, Cloud Run, etc.)

1. Push this repo and deploy as a normal Node service.

2. Set the same secret environment variables in the host dashboard.

3. The process runs npm start → node dist/index.js, which listens on PORT.

npm install
npm run build
npm start

Connect from Claude

Claude (web / desktop connectors)

Add a custom connector with your HTTPS MCP URL, for example:

https://your-service.example.com/mcp

If you set MCP_AUTH_TOKEN, configure the matching bearer token in the connector settings when supported.

Claude Code

claude mcp add --transport http instagram-claude-mcp https://your-service.example.com/mcp

Cursor

Add to .cursor/mcp.json (or your MCP config):

{
  "mcpServers": {
    "instagram-claude-mcp": {
      "url": "https://your-service.example.com/mcp"
    }
  }
}

Instagram API notes

• Uses only the official Meta Graph API (graph.facebook.com or graph.instagram.com).

• Credentials are read from environment variables only — never hardcoded.

• Insights metrics and periods depend on Meta’s current Insights API rules (metric availability differs for account vs media, and by media product type). Pass the metrics Meta documents for your use case via the metrics tool argument.

• Tokens expire; rotate long-lived tokens as needed in your host’s secret store.

Project layout

src/
  app.ts                # Express app factory (/health, /mcp) — default-exported for Vercel
  index.ts              # Entry: export app; listen only when not on Vercel
  config.ts             # Environment configuration
  mcp-server.ts         # MCP tool registration
  instagram/client.ts   # Official Graph API client (read-only)
vercel.json             # Vercel Express + function limits

License

MIT