MenuClose
Journal

· Tech · 5 min read

Manage Instagram and Facebook with Claude and social-mcp

Set up social-mcp, a self-hosted MCP server that lets Claude post, schedule and analyse content on Instagram and Facebook.

Posting photos to Instagram and Facebook means choosing shots, staging them, writing captions and publishing on a schedule. social-mcp hands this work to Claude.

social-mcp is a free, self-hosted MCP server. It runs on your own machine and connects Claude Code or Claude Desktop to the Meta Graph API. Claude gets tools to post photos, carousels and Reels to Instagram and a Facebook Page, to schedule posts and to read engagement analytics. The access token is configured locally and sent to Meta for authentication.

Requirements

  • A Meta App (type: Business) with Facebook Login for Business and the Instagram Graph API enabled
  • A long-lived User Access Token with these scopes:
    • pages_show_list, pages_read_engagement, pages_manage_posts
    • instagram_basic, instagram_content_publish
  • An Instagram Business or Creator account connected to a Facebook Page. A personal Instagram account is not enough: the Instagram Graph API requires a Business or Creator account for publishing.
  • Docker Compose (recommended) or Python 3.8+
  • Claude Code or Claude Desktop as the MCP client

1. Create a Meta App and a token

In the Meta for Developers console, create an app of type Business and add Facebook Login for Business and the Instagram Graph API. Then generate a long-lived User Access Token with the scopes listed above.

You also need two IDs: your Facebook Page ID and your Instagram User ID. The project’s setup guide describes every step, including the curl commands for the token exchange.

Long-lived user tokens last about 60 days. social-mcp includes a check_token_validity tool, so you or Claude can check the expiry date and exchange the token again before it runs out.

2. Clone social-mcp

Clone the repository to a permanent location on the machine that will run it, for example a homelab server or a VPS:

git clone https://github.com/bmachek/social-mcp.git
cd social-mcp
cp .env.example .env

3. Configure your credentials

Open .env and fill in at least these values:

META_USER_TOKEN=<your long-lived user token>
META_PAGE_ID=<your Facebook Page ID>
META_IG_USER_ID=<your Instagram User ID>

All other settings have defaults. The MCP server listens on port 3224, the nginx file sidecar on port 3223.

4. Start the server

docker compose up -d --build

This starts two containers:

  • instagram-mcp: the MCP server on MCP_PORT (default 3224)
  • instagram-mcp-files: an nginx sidecar on FILE_SERVER_PORT (default 3223). It serves each image briefly at a one-time public URL so Meta can fetch it, then removes it again.

To run it with plain Python instead of Docker:

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

5. Connect Claude

Claude Code:

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

Claude Desktop: go to Settings → Developer → Custom Connectors → Add and enter this URL:

http://<host>:3224/mcp

Claude now has access to all social-mcp tools.

6. Post

Put photos or videos into data/images/ and tell Claude in plain language what to do. Some examples:

  • “Post the sunset shot from my inbox to Instagram and Facebook with this caption, and add it to my story.”
  • “Make an Instagram carousel from these four frames and schedule it for tomorrow at 19:30.”
  • “Show me my top-performing posts from the last 30 days so I can reuse the caption style.”

Files move from the inbox to the platforms and are archived after a successful post:

data/images/  →  stage → publish  →  Instagram / Facebook Page
                     ↓ on success
                 data/posted/YYYY-MM-DD/

Plan two weeks with the autopilot

Instead of planning posts one by one, you can let Claude propose a complete schedule:

  1. autopilot_plan scans your inbox, removes duplicate burst shots by perceptual hash, groups photos taken close together in time and place into carousels, and proposes a two-week posting schedule.
  2. You review the plan and write captions where you want them.
  3. autopilot_commit validates everything and queues all posts at once.

Security and data

social-mcp has no built-in authentication. Anyone who can reach it on the network can use it. Keep it on your LAN. If you need access from outside, put a reverse proxy in front of it that terminates TLS and checks a bearer token. The README includes a Caddy example for exposing the file sidecar over Tailscale/Headscale.

The server runs on hardware you control. Your token is stored in the local .env file and sent to Meta to authenticate API requests. Media you select is uploaded to Meta or made temporarily available for Meta to fetch.

Publishing is subject to Meta’s current API quotas and account permissions. The server checks the publishing limits before posting. If a job is refused, check the current setup guide and the API response.

Source code

social-mcp is free. The source code is on GitHub at github.com/bmachek/social-mcp. The project page lists all features.

Back to the journal