social-mcp

A self-hosted MCP server that gives Claude the ability to manage your Instagram and Facebook Page — post photos, carousels, and Reels, schedule posts, pull engagement analytics, and run an autopilot that plans and queues two weeks of content from your photo inbox in one go.

You drop files into a folder, ask Claude what to post and when, and it handles the rest: staging, uploading, archiving, and scheduling. Everything runs on your own machine; no third-party service touches your tokens or your media.

What you can do with it

Post immediately

Photo to Instagram feed + Story
Photo to Facebook Page feed + Story
Both platforms at once (one command, file archived once)
Carousel (2–10 photos) to IG, FB, or both
Reel / video to IG, FB, or both
Cross-post to Facebook Groups

Schedule for later

Any of the above, at a specific time or relative (in 2h, tomorrow at 19:30)
Persistent scheduler survives container restarts

Analytics

Account-level reach, engagement, followers (IG and FB)
Per-post insights — likes, comments, shares, saves, plays
Top-performing posts ranked by engagement (useful as caption examples)

Autopilot

autopilot_plan — scans your inbox, deduplicates burst shots by perceptual hash, clusters photos taken close together in time and place into carousels, and proposes a two-week posting schedule
You review the plan and write captions
autopilot_commit — validates and queues everything at once

How it works

The server implements the Model Context Protocol (MCP), which is the standard way to give AI assistants access to external tools. Claude Code (or Claude Desktop) connects to it and gains a set of posting/scheduling/analytics tools backed by the Meta Graph API.

For local files, an nginx sidecar briefly serves each image at a one-shot public URL so Meta's servers can fetch it; the URL is torn down and the file is archived once the post goes through. Facebook uploads go direct — no public URL needed.

Your photo inbox          MCP server               Meta Graph API
  data/images/    →   stage → publish    →   Instagram / Facebook Page
                      ↓ on success
                  data/posted/YYYY-MM-DD/

Setup

See SETUP.md for the full step-by-step guide (Meta App creation, token generation, .env configuration, Docker Compose, reverse proxy).

Quick summary:

Create a Meta App (type: Business) and add Facebook Login for Business + Instagram Graph API.
Generate a long-lived User Access Token with the scopes below.
Copy .env.example → .env and fill in your token, Page ID, and IG User ID.
docker compose up -d --build
Register the server with your MCP client (Claude Code or Claude Desktop).

Required token scopes

Scope	Required for
`pages_show_list`	Everything — used to derive the Page Access Token
`pages_read_engagement`	Analytics
`pages_manage_posts`	FB Page publishing
`instagram_basic`	IG account info
`instagram_content_publish`	IG publishing
`publish_to_groups`	FB Group cross-posting (optional)

Running

Docker Compose (recommended)

cp .env.example .env
# edit .env

docker compose up -d --build

Two containers start:

instagram-mcp — MCP server on MCP_PORT (default 3224)
instagram-mcp-files — nginx sidecar on FILE_SERVER_PORT (default 3223) for image staging

Plain Python

cp .env.example .env
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
python server.py

Connecting an MCP client

Claude Code

claude mcp add instagram -- docker run --rm -i \
  --env-file /opt/social/.env \
  instagram-mcp:latest

Or in .mcp.json:

{
  "mcpServers": {
    "instagram": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "--env-file", "/opt/social/.env", "instagram-mcp:latest"]
    }
  }
}

Claude Desktop

Settings → Developer → Custom Connectors → Add:

http://<host>:3224/mcp

MCP transports

`MCP_TRANSPORT`	Use when	Client URL
`streamable-http` (default)	Persistent container, Claude Desktop, LAN clients	`http://<host>:3224/mcp`
`sse`	Same, legacy transport	`http://<host>:3224/sse`
`stdio`	Claude Code spawns container per call	stdio (no network)

No built-in auth — restrict at the network layer or put a TLS-terminating proxy with a bearer-token check in front if you expose beyond the LAN.

File layout

data/
├── images/          # drop photos and videos here before posting
├── public/          # transient: nginx serves staged files here
├── posted/          # archived after successful publish, by date
│   └── YYYY-MM-DD/
└── scheduler/       # APScheduler SQLite jobstore

Tool reference

Posting

Tool	What it does
`post_instagram_photo(image_url, caption, alt_text)`	IG feed photo from a public URL
`post_facebook_photo(image_url, caption)`	FB Page photo from a public URL
`post_instagram_local_photo(filename, caption, alt_text, also_story)`	IG feed photo from inbox; stages, posts, archives
`post_facebook_local_photo(filename, caption, also_story, group_ids)`	FB Page photo from inbox; direct multipart upload
`post_local_photo_dual(filename, caption, alt_text, also_story_ig, also_story_fb)`	Both platforms in one job
`post_instagram_local_carousel(filenames, caption)`	IG carousel (2–10 photos)
`post_facebook_local_carousel(filenames, caption)`	FB multi-photo post (2–10 photos)
`post_local_carousel_dual(filenames, caption)`	Carousel to both platforms
`post_instagram_reel(video_url, caption, share_to_feed)`	IG Reel from a public URL
`post_instagram_local_reel(filename, caption, share_to_feed)`	IG Reel from inbox
`post_facebook_video(video_url, caption)`	FB Page video from a public URL
`post_facebook_local_video(filename, caption)`	FB Page video from inbox
`post_facebook_local_reel(filename, description)`	FB Page Reel from inbox
`post_local_reel_dual(filename, caption, share_to_feed)`	Reel to both platforms

Scheduling

Tool	What it does
`schedule_instagram_local_photo(filename, when, caption, also_story)`	Queue an IG photo post
`schedule_facebook_local_photo(filename, when, caption, also_story)`	Queue a FB photo post
`schedule_instagram_local_carousel(filenames, when, caption)`	Queue an IG carousel
`schedule_facebook_local_carousel(filenames, when, caption)`	Queue a FB carousel
`schedule_instagram_local_reel(filename, when, caption, share_to_feed)`	Queue an IG Reel
`schedule_facebook_local_video(filename, when, caption)`	Queue a FB video post
`schedule_facebook_local_reel(filename, when, description)`	Queue a FB Reel
`list_scheduled_posts()`	Show pending jobs
`cancel_scheduled_post(job_id)`	Remove a pending job

when accepts in 2h, in 1d, or an ISO timestamp (Europe/Berlin if naive).

Inbox

Tool	What it does
`list_pending_images()`	List postable photos in `data/images/`
`list_pending_videos()`	List postable videos in `data/images/`
`show_image(filename, max_side)`	Render an inbox image inline so Claude can see it

Analytics

Tool	What it does
`get_instagram_account_insights(metric, period, since_days)`	Account-level IG metrics (reach, engagement, followers)
`get_instagram_post_insights(media_id, metric)`	Per-post IG metrics
`get_facebook_page_insights(metric, period, since_days)`	Page-level FB metrics
`get_facebook_post_insights(post_id, metric)`	Per-post FB metrics
`top_performing_posts(platform, limit, top_n)`	Rank recent posts by engagement
`list_recent_instagram_posts(limit)`	Raw IG media list
`list_recent_facebook_posts(limit)`	Raw FB Page post list

Autopilot

Tool	What it does
`autopilot_plan(days_ahead, max_posts, slots_per_day, …)`	Analyse inbox, dedup, cluster into carousels, propose a schedule
`autopilot_commit(plan)`	Validate and queue the filled-in plan

Utility

Tool	What it does
`check_token_validity()`	Inspect token scopes, type, and expiry

Meta API notes

Graph API version: v25.0 (latest stable as of 2026-02-18). Set via GRAPH_API_VERSION in .env.
IG rate limit: 50 posts per 24-hour rolling window. The server checks before each publish and refuses if the quota is full.
Container polling: IG requires a two-step create → publish flow with a status poll in between. Photos time out after 90 s; Reels after 600 s (both configurable in .env).
Token lifetime: Long-lived user tokens last ~60 days. Use check_token_validity to monitor, and re-exchange before expiry. See SETUP.md for the renewal curl command.
Errors: Meta errors are surfaced verbatim — code, error_subcode, message, fbtrace_id, and the user-facing message — rather than being swallowed.

Reverse proxy (Caddy)

The nginx sidecar speaks plain HTTP. If Caddy runs on a remote VPS and reaches this host over Tailscale/Headscale:

social.example.com {
    reverse_proxy <homelab-tailscale-name>:3223
}

Set PUBLIC_BASE_URL=https://social.example.com in .env.

Name		Name	Last commit message	Last commit date
nginx		nginx
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
SETUP.md		SETUP.md
autopilot.py		autopilot.py
diagnose.py		diagnose.py
docker-compose.yml		docker-compose.yml
exif_reader.py		exif_reader.py
local_files.py		local_files.py
meta_client.py		meta_client.py
pyproject.toml		pyproject.toml
requirements.txt		requirements.txt
scheduler.py		scheduler.py
server.py		server.py

Navigation Menu

Repository files navigation

social-mcp

What you can do with it

How it works

Setup

Required token scopes

Running

Docker Compose (recommended)

Plain Python

Connecting an MCP client

Claude Code

Claude Desktop

MCP transports

File layout

Tool reference

Posting

Scheduling

Inbox

Analytics

Autopilot

Utility

Meta API notes

Reverse proxy (Caddy)

About

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

social-mcp

What you can do with it

How it works

Setup

Required token scopes

Running

Docker Compose (recommended)

Plain Python

Connecting an MCP client

Claude Code

Claude Desktop

MCP transports

File layout

Tool reference

Posting

Scheduling

Inbox

Analytics

Autopilot

Utility

Meta API notes

Reverse proxy (Caddy)

About

Topics

Resources

Stars

Watchers

Forks

Contributors

Languages