Getting started

Use the dashboard for account connection and post management. Use an API key to connect the API, CLI, or an agent to your organisation.

Using an AI agent?

Copy these instructions into your AI agent. They include the docs links, client setup steps, and publication checks.

Start with the documentation index, or read all docs as Markdown. Use the Copy Markdown control on any page to copy that page.

Connect an account

Sign in or create an account.
Open Accounts and select Connect an account.
Select a platform and complete its connection steps. For OAuth platforms, sign in with the platform and grant the requested permissions.
Confirm that the account status is Connected.

For Bluesky, use your handle and an app password. For Instagram, TikTok, and YouTube, see the platform guide.

If a platform shows Setup required, contact the service administrator. If an account shows Needs reconnect, connect that account again.

Create your first post

Open Posts and create a post.
Select the connected accounts that must receive the post.
Enter text, attach media, and set the required platform options.
Validate the post and correct each reported error.
Save a draft, publish now, or select a date and time to schedule the post.

A publish request starts the publication process. Check the status of each publication before you report that the post was published. A post can succeed on one platform and fail on another.

Create an API key

Open API keys and create a key. Copy the full key when it is shown. The key is shown only once. The prefix in the key list cannot authenticate requests.

Select the permissions your client needs. An empty scope list gives full access. For the agent workflow below, a restricted key needs accounts:read, capabilities:read, posts:read, and posts:write. Add media:write for uploads and events:read to read events.

Select How to use on the API keys page for CLI, MCP, and REST connection instructions. Keep the key private.

If a key is exposed or no longer needed, select its Revoke API key row action and confirm. The key stops working for CLI, REST, and MCP requests. You can also run bun run cli -- keys revoke key_example with a full access key or a key that has keys:write. Replace key_example with the key ID from bun run cli -- keys list. Revocation cannot be undone.

Use an agent

Add Open Social to your MCP client with the instructions in How to use. Ask the agent to list your connected accounts to check its connection.

For a client that supports an MCP JSON configuration, use this template:

JSON

{
  "mcpServers": {
    "open-social": {
      "command": "bun",
      "args": ["--cwd", "/absolute/path/to/open-social", "run", "mcp"],
      "env": {
        "OPEN_SOCIAL_BASE_URL": "https://opensocial.run",
        "OPEN_SOCIAL_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Install Bun and the repository dependencies with bun install first. Replace the repository path and API key. For a local or self-hosted service, also replace the service address. This MCP server uses stdio. The client starts it as a local process. It does not use a remote MCP URL. Keep the configuration private. Use the client's secret storage if available.

Use these tools in this order:

Step	MCP tool	Purpose
1	`social_accounts_list`	Get connected accounts and their IDs.
2	`social_capabilities_get`	Read text limits, media limits, and platform requirements.
3	`social_account_publishing_options`	Read current TikTok privacy choices and creator limits.
4	`social_media_upload`	Upload an attachment and get its media ID, if needed.
5	`social_post_validate`	Check text, attachments, and options for the target accounts.
6	`social_post_create`	Create a draft, or set `publish_at` to schedule the post.
7	`social_post_publish` or `social_post_schedule`	Publish a draft or set its publication time.
8	`social_post_status`	Check the post and each publication result.
9	`social_events_list`	Read recent events, if needed.

Pass account IDs from the account list. Use media IDs returned by the upload tool. Do not guess IDs or platform limits. For TikTok, ask the creator to choose the privacy level and confirm consent for each video.

The create and validate tools apply the same platform_options to all target accounts. Use separate tool calls when accounts need different options.

Use the CLI or API

The How to use dialog supplies the client connection instructions. After CLI setup, run these commands from the open-social repository directory:

Shell

export OPEN_SOCIAL_BASE_URL="https://opensocial.run"
export OPEN_SOCIAL_API_KEY="YOUR_API_KEY"
bun run cli -- accounts list
bun run cli -- capabilities bluesky
bun run cli -- posts validate --text "Hello from Open Social" --account acct_YOUR_ACCOUNT
bun run cli -- posts create --text "Hello from Open Social" --account acct_YOUR_ACCOUNT
bun run cli -- posts publish post_YOUR_POST
bun run cli -- posts status post_YOUR_POST

Replace the account ID with an ID from the account list. Replace the post ID with the ID returned by the create command. Choose a platform that matches your account. Run bun run cli -- --help for available commands.

For a local or self-hosted service, replace https://opensocial.run with your service address. Set the API key in your local environment. Do not commit it to the repository.

For REST requests, send your API key in the Authorization header. Use the same service address as the dashboard, with the /v1 path. See the API reference for request bodies and response fields.

To check a REST connection, use the same environment variables:

Shell

curl --fail-with-body "$OPEN_SOCIAL_BASE_URL/v1/accounts" \
  -H "Authorization: Bearer $OPEN_SOCIAL_API_KEY"

Using an AI agent?Copy Anchor Link

Connect an accountCopy Anchor Link

Create your first postCopy Anchor Link

Create an API keyCopy Anchor Link

Use an agentCopy Anchor Link