Ghost in the Box MCP Server

Welcome to the garden 🌱 (what this is)

Good conversations need more than a publish button. Ghost in the Box connects the work around it: understand the conversation, keep the sources, develop a draft, choose the account, send the exact job, and remember what happened.

Built by Digital Disconnections for people who want to own their tools and keep control of their work. Read our mission statement, It's Not 1997.

New words such as brief, lane, frozen job or Bat are explained in plain terms.

Related MCP server: so-easy-mcp

Pick a plot (supported platforms)

Facebook, TikTok, and YouTube currently have brief formats, not built-in publishing adapters. The outbox refuses them, so you post those yourself. Provider access changes, so mocked tests establish local behavior rather than a guarantee that your account is connected.

Plant your first seed (install and first run)

You need Python 3.11 or newer (python3 --version) and Git.

git clone https://github.com/Digital-Disconnections-LTD/ghost-in-the-box.git
cd ghost-in-the-box
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e '.[recommended]'
python -m playwright install chromium
ghost-in-the-box doctor

doctor checks this machine and prints the exact command for anything missing. It reads local files only. ghost-in-the-box --help lists every command by group, ghost-in-the-box config shows where your files live, and ghost-in-the-box --version prints the installed version. The command index has one line per command.

Try the offline example before connecting anything. It builds a brief, drafts and queues a post in a local outbox, and previews the send with publish --dry-run. Nothing logs in and nothing is sent.

Then connect your chosen accounts with the login wizard and use the same ghost-in-the-box command for accounts, briefs, inboxes, and delivery.

What each extra unlocks

The base install only needs Requests. Extras add optional features.

Combine extras with commas, for example '.[recommended,substack]'. LinkedIn reads and posts need only the base install once a session exists.

Where it runs

"Tested" means the offline test suite runs there in CI. Mocked tests prove local behaviour, not that a platform will accept your account today.

Browser-guided logins

ghost-in-the-box login start opens the Chrome you already have (or Edge, Brave or Chromium). It starts it as a normal program with its own profile folder under the state dir, so you sign in the way you always do. Google sign-in works too.

A numbered menu shows which accounts are already connected. Pick one, sign in, and the menu comes back until you say done. Instagram and Threads share one Meta login, so after one you are offered the other with no second sign-in. You never type your handle: the wizard reads it from the session and asks you to confirm.

What gets saved is a cookie session in files private to you. Nothing leaves your machine unless you export it. login forget-browser --platform PLATFORM wipes a browser profile, and login export and login import move the sessions you pick to a server. Every step is in the login guide.

Bring a Bat, or your favorite MCP client 👻 (agents and MCP)

Ghost in the Box works alongside Batbox, Claude Desktop, Claude Code, Codex CLI and other MCP clients. The Instagram, LinkedIn and Substack servers speak standard MCP over stdio. Ready-made client configs live in examples/. Threads is CLI-only today; an agent reaches it through the ghost-in-the-box command.

Set up MCP → · Connect the platforms → · Follow the agent workflow →

Your garden stays yours (privacy and safety)

Accounts, cookies, drafts, inboxes, and receipts live in your local state directory. Ghost in the Box has no project-operated telemetry collector or analytics uploader. Social requests go to the platforms you connect; optional image inspection sends selected images to your configured vision endpoint. Those services control their own data practices.

Configuration and state explains the paths and optional helpers. Credentials and real account exports belong outside Git.

A few things to know before you connect a real account:

• Sessions are credentials. A saved session or an export bundle lets anyone who holds it act as you. Keep them private and out of Git, chats and screenshots.

• Platform terms apply. These tools use your own login, not an official developer API. Automated use may break a platform's terms and can get an account challenged or restricted. You decide what is acceptable for your account.

• Nothing publishes by accident. Login, import, brief, draft, queue and publish --dry-run never post. A post goes out only when you run ghost-in-the-box publish JOB, a timer you installed runs publish --due, you run threads publish JOB or threads retry JOB, you add --now to a threads command, or an MCP client calls a publishing tool such as instagram_publish_job.

Research use only

This code is for research purposes only. Follow the rules: use it only with accounts you own, respect each platform's terms of service and rate limits, and take responsibility for anything you publish.

Come grow with us (contributing)

This is a community project. Your fixes, improvements, testing, documentation, and artwork are welcome. AI-assisted code is welcome with regression tests.

We would love help with more provider adapters, clearer account setup, better conversation context, and a friendly interface over the existing inbox and outbox. Start with CONTRIBUTING.md and the roadmap.

Project-owned code uses the MIT license. Required dependency attribution is preserved in Third-party notices.