jorgex-social-mcp
Enables scheduling and publishing images, carousels, reels, and stories to a single Instagram professional account; captures insights snapshots and maintains their history; and replies to comments and direct messages according to configured rules within Meta/Instagram limits.
jorgex-social
Self-hosted, agent-first tool for your own Instagram professional accounts: schedule and publish posts, keep insights history, and reply to comments and direct messages by rules. Everything is done through an authenticated REST API, so an AI agent can operate it end to end.
Status: early. It runs in production for one operator's own accounts, but expect breaking changes until a first release.
What it does
Publishes images, carousels, reels and stories to your own Instagram professional accounts, at the time you schedule (the Instagram API does not schedule; the worker does). A reel can go out as a trial reel, shown only to non-followers until you share it with followers in the Instagram app, or until Instagram does it for you if it performs well.
Takes insights snapshots and keeps their history, beyond the 90 days Instagram keeps.
Replies to comments and direct messages by rules ("if a comment on this post contains X, reply with one of these versions"), within Meta's limits: one private reply per comment within 7 days, and direct messages only within 24 hours of the person's last message.
Runs several of your own Instagram professional accounts in one installation. Each one has its own credential, posts, rules, replies, statistics, kill switch and token, and the web interface switches between them. Nothing is combined or totalled across accounts.
Exposes all of it through a REST API, a thin MCP server for agents, and a web interface that shows it. Each installation sets the interface's own name, CSS and icon (Your own look).
Related MCP server: ClaudeMetaMCP
What it does not do
Start conversations or send bulk or promotional messages.
Store the text of comments or messages. It reads them in memory, matches them against the rules and discards them; only Instagram identifiers, dates and status are kept. There is no inbox and no conversation history.
Serve other people's accounts. With standard access the Meta app only reaches accounts that have a role in it, and serving someone else's account needs Meta's advanced access, which is out of scope.
Serve several operators, combine accounts in one view or total, or serve other networks.
One installation, several accounts
An installation has one operator and one Meta app, and serves one or more Instagram professional
accounts, all of them yours. Connect each account with connect-instagram and then create one
token per account per agent (create-token --account): a token sees one account and can reach no
other. The interface opens each account at /ui/a/{account}/.
Some things belong to the installation, not to one account: the appearance (product name, icon and
CSS; any token with account:write changes the name and icon for all, while the CSS is only written
from Settings), the catalog of post types and limits, /health, and the webhook configuration.
What you need
A server with Docker and the Compose plugin.
For real mode: one or more of your own Instagram professional accounts, your own Meta app, and a public domain served over HTTPS.
Every installation uses its own Meta app. With the app in development and standard access, each account you connect must also have a role (tester) in that app; see Create your Meta app.
Simulation needs none of the real-mode requirements: a fresh install runs against a fake Instagram and never calls Meta.
Install
git clone <repository-url> jorgex-social && cd jorgex-social
cp .env.example .env
docker compose up -d --build
curl http://127.0.0.1:8000/health # {"status":"ok","simulation":true}INSTALL.md covers the rest: connecting each own account, API tokens, the reverse proxy, the web interface, creating your Meta app step by step, switching to real mode, the webhook, backups and upgrades.
Before you use it
No support. The code is public so anyone can run their own installation; nobody provides accounts, hosting or support. Issues and pull requests are read when possible, with no commitment.
Not affiliated with Meta. Instagram and Meta are trademarks of Meta Platforms, Inc.
You are responsible for your installation: following Meta's platform terms and its policies on automated messages, your own legal obligations towards the people who write to you, and keeping the installation updated.
Security: see SECURITY.md. Never paste tokens or secrets into issues.
Development
Requires Python 3.14 and uv.
uv sync
uv run jorgex-social migrate
uv run jorgex-social connect-instagram # simulation: the fake account takes any placeholder token
uv run jorgex-social create-token --name my-agent --account simulated_account \
--grant posts=write --grant stats=read
uv run jorgex-social create-operator && uv run jorgex-social enroll-totp # for /ui
uv run jorgex-social serve # API on http://127.0.0.1:8000, docs at /docs, web interface at /ui
uv run jorgex-social worker # background worker
uv run pytest
uv run ruff check . && uv run ruff format --check .A token works on the one account named with --account (its username or id) and can read and write
nothing of any other: connect every account you own and create one token per account per agent.
Connecting the same account again refreshes its credential; the posts, rules and tokens it already
has stay as they are.
Configuration comes from JORGEX_SOCIAL_* environment variables; see .env.example. A fresh install runs
in simulation mode and never calls Meta.
To go live, set JORGEX_SOCIAL_SIMULATION=false and connect each of your own accounts with
uv run jorgex-social connect-instagram, which reads a long-lived Instagram token from standard input
without echoing it (--token arguments would end up in the shell history, so there is none). The token
is stored encrypted with AES-GCM under the key in JORGEX_SOCIAL_SECRET_KEY_FILE, which migrate
creates with mode 600. Back that key up separately from the database. The worker renews each token
before it expires, and GET /v1/account reports the connection status, open incidents and the kill
switch of the token's account. If Instagram reports an account as restricted, that account's kill
switch turns on by itself and stays on until you turn it off (see
Protecting the account).
MCP server
With a public URL, the service itself is an MCP server at /mcp: an agent connects with only that
URL and signs in through OAuth, with the operator's consent (see
Remote MCP). The rest of this section is the local alternative.
jorgex-social-mcp is a thin MCP server (stdio) that runs on the agent's machine and turns each
tool into one call to the REST API. It runs from a clone of this repository (uv sync;
the package is not on PyPI) and needs two environment variables: JORGEX_SOCIAL_URL, the base URL
of the API, and JORGEX_SOCIAL_TOKEN, an API token created with create-token. At startup it reads
the token's permissions from GET /v1/token and exposes only the tools that token can use; the API
still checks every call. API errors reach the agent as they come, with their stable code.
Most agent clients take a JSON entry like this one (the exact file and key depend on the client):
{
"mcpServers": {
"jorgex-social": {
"command": "uv",
"args": ["run", "--directory", "/path/to/jorgex-social", "jorgex-social-mcp"],
"env": {
"JORGEX_SOCIAL_URL": "http://localhost:8000",
"JORGEX_SOCIAL_TOKEN": "jxs_your_token_here"
}
}
}
}Give the agent its own token with only the groups it needs, for the account it should work on: that
token reaches that account and no other, and GET /v1/token says which one (account.id is the
account's id on the network, account.connection_id the one this installation gives it). For a
second account, add a second MCP entry with its own token; neither sees the other. A token
of the simulated account is refused by a service in real mode, and the other way round. The URL must use HTTPS
unless the API is on the same machine (localhost, 127.0.0.0/8 or ::1): the token travels in
every request. With the recommended proxy the API is not public, so http://localhost:8000 goes
through the SSH tunnel described in INSTALL.md.
License
MIT. See LICENSE.
The web interface ships the Outfit, Inter and JetBrains Mono fonts, which are not under MIT: each is
licensed under the SIL Open Font License 1.1, whose text is next to the font files in
src/jorgex_social/ui/static/fonts/.
Dependencies are installed from PyPI and keep their own licenses.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Agent-first social media publishing, scheduling, analytics, and unified inbox API + 16-tool MCP server across 18 social platforms (X, LinkedIn, Instagram, YouTube, TikTok, Threads, Bluesky, Reddit, Telegram, Discord, Mastodon, Facebook, Pinterest).
Instagram MCP for DM and comment automation, AI Agent and content publishing via Meta's official API
MCP server for QPost — lets AI agents publish video and image posts to YouTube, TikTok, Instagram.
MCP server for AI agents: posts, messages and comments on WhatsApp, Instagram, TikTok and Facebook.
Related MCP Servers
- AlicenseAqualityDmaintenanceMCP server that wraps Meta's Messenger Platform, Instagram Messaging, and comment moderation APIs as semantic tools for LLM agents to read inbox, reply, and moderate comments.16MIT
- FlicenseAqualityNot gradedmaintenanceLocal MCP server for operating Instagram, Meta Ads, and Facebook Page from Claude Code via Meta's Graph API. Provides 20 tools for publishing, campaign management, and insights.20-
- AlicenseNot gradedqualityCmaintenanceMCP server for Instagram Graph API integration, enabling AI applications to manage Instagram Business accounts: fetch profiles, media, insights, publish content, and handle DMs.MIT
- FlicenseNot gradedqualityDmaintenanceA production-ready MCP server for interacting with Instagram/Meta APIs, enabling AI agents to manage content, analyze performance, research competitors, and handle publishing workflows.-