Skip to main content
Glama
jorgex-social-mcp

jorgex-social-mcp

by jorgehn98

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…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      MCP 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.
      16
      MIT
    • F
      license
      A
      quality
      Not graded
      maintenance
      Local 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
      -
    • A
      license
      Not graded
      quality
      C
      maintenance
      MCP server for Instagram Graph API integration, enabling AI applications to manage Instagram Business accounts: fetch profiles, media, insights, publish content, and handle DMs.
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      A production-ready MCP server for interacting with Instagram/Meta APIs, enabling AI agents to manage content, analyze performance, research competitors, and handle publishing workflows.
      -