1Social MCP

Model Context Protocol server for publishing to social networks — secured by OAuth.

1Social MCP lets an AI assistant post for you. Connect Claude, ChatGPT, Cursor, VS Code, or a CLI client to 1Social, then publish, schedule, check and fix posts across Instagram, TikTok, X, LinkedIn, Bluesky, Threads and Facebook in natural language.

• Server URL: https://mcp.1social.dev/mcp
• Transport: Streamable HTTP
• Auth: OAuth 2.1 with PKCE and Dynamic Client Registration
• Landing & setup: 1social.dev/mcp

Install

1Social MCP is a remote, OAuth-secured server. There is no package to install and no API key to paste. Add this to your client's MCP config:

{
  "mcpServers": {
    "1social": {
      "url": "https://mcp.1social.dev/mcp"
    }
  }
}

One-click install: Cursor · VS Code · Claude connectors · ChatGPT connectors

CLI clients (Claude Code, Gemini CLI, Codex CLI) and manual snippets: see Supported clients.

Quick start

1. Create a 1Social account at 1social.dev.
2. Connect your social accounts in the browser. This step needs a browser and cannot be done from a chat — each network's OAuth consent screen has to be signed for by you.
3. Add the server to your client with the one-click link, the CLI command, or the JSON/TOML snippet above.
4. Authorize with OAuth when your client opens the consent screen.
5. Ask your assistant to post.

What you can do from chat

• 📤 Publish and schedule — one message goes to every network you pick, now or up to 30 days ahead.
• 🔍 Check before it goes — per-network character counts, whether an image is required, whether a multi-part post will thread natively or be joined, and what it costs against your quota.
• 🧾 Read the receipt — what reached each network, what failed and why, and what genuinely could not be determined.
• ♻️ Fix what broke — retry one network without touching the ones that already went out.
• 🖼 Attach media — post an image or video from the chat. Instagram and TikTok refuse posts without one.
• ✏️ Edit, cancel, delete — change a scheduled post, unschedule it, or delete it from the networks that allow deletion.

Tool surface

Ten tools, deliberately few. Publish-now and schedule are the same tool (scheduledAt: null means now), and reading one post is list_posts with a postId rather than a second tool — a smaller set is one a model picks from accurately.

The live set is what the server says it is — run tools/list against https://mcp.1social.dev/mcp for the exact, current shapes.

It tells you when it doesn't know

A post to four networks can land on three. Every tool result is per network: the failure is named in words you can act on, and a delivery whose outcome genuinely could not be determined comes back as unknown rather than as success.

unknown is not a dead end. You look at the network, tell the assistant what you see, and confirm_delivery settles it — confirming it is live commits the quota, confirming it is not marks the delivery failed so retry_delivery can pick it up. The assistant is not allowed to guess this on your behalf.

What deletion can and cannot do

delete_post always removes the post from 1Social. Removal from the network depends on the network:

On a multi-part thread only the first post is removed; the rest stay live as orphans. The tool reports what actually came down, per network, and the assistant is instructed to tell you that rather than confirm a clean delete.

Plans & access

Publishing costs us money per delivery, so the quota is metered in deliveries, not posts — one post to four networks is four deliveries. A delivery to X costs more units than the others because X charges per post (pricing has the current numbers).

A new account has a small free monthly allowance — enough to publish, watch the receipt come back, retry something, and schedule a post — so the tools work before you pay for anything. A failed delivery does not count against the quota when the failure was ours or the network's.

You never have to leave the chat to pay. A tool call that runs out of quota comes back with a checkout link for your account.

Supported clients

• Claude (web & desktop) — Settings → Connectors → Add custom connector
• ChatGPT — Settings → Apps & Connectors → Advanced → Developer mode → Add custom connector
• Cursor — one-click deeplink, or ~/.cursor/mcp.json
• VS Code — one-click deeplink, or .vscode/mcp.json
• Claude Code (CLI) — claude mcp add --transport http 1social https://mcp.1social.dev/mcp
• Gemini CLI — gemini mcp add --transport http 1social https://mcp.1social.dev/mcp
• Codex CLI — codex mcp add 1social --url https://mcp.1social.dev/mcp
• Generic HTTP MCP client — point it at the URL and let it complete OAuth discovery

Full per-client instructions: docs/setup.md.

Cursor plugin

This repository is also a Cursor plugin. It contributes one MCP server (1social) and no rules, skills, agents, or hooks.

.cursor-plugin/plugin.json   ← plugin manifest
mcp.json                     ← the MCP server it contributes
assets/logo.svg              ← plugin logo

There is nothing to configure. The server advertises OAuth 2.1 metadata, Cursor registers itself dynamically, and the consent screen opens on first use.

Example prompts

Cross-post with a check first

"Draft a post about our new pricing page for LinkedIn, X and Bluesky, check it fits, then publish."

→ preview_post reports the per-network counts and cost; publish_post returns a receipt per network.

Schedule with an image

"Post this screenshot to Instagram and Threads on Friday at 9am."

→ The attached file goes in media; Instagram would have refused the post without it.

Find out what actually happened

"Did yesterday's post make it everywhere?"

→ list_posts returns the receipt — including any delivery still marked unknown.

Repair, not repost

"LinkedIn failed. Retry just LinkedIn."

→ retry_delivery touches one delivery and leaves the successful networks alone.

More: docs/examples.md.

Authorization

OAuth 2.1 with PKCE, per the MCP authorization spec. The authorization server is https://1social.dev; it supports Dynamic Client Registration, so compatible clients set themselves up and you only see the consent screen. Scopes granted are openid, profile, email and offline_access.

The assistant never sees your social credentials. Your network tokens stay in 1Social; the assistant holds only a token for your 1Social account, and you can revoke it at any time from the web app.

Flow details: docs/oauth.md.

Troubleshooting

Common connection, OAuth, and tool-call errors: docs/troubleshooting.md.

Marketplace listings

This repo is the source for two listings:

The tools array in lhm.plugin.json is generated from the TOOLS table in the server's own contract (packages/contract/src/mcp/tools.ts in the private repo), the same table that answers tools/list. It is a snapshot: when the tool surface changes, regenerate it rather than hand-editing, or the listing will describe a server that no longer exists.