social-mcp

An MCP (Model Context Protocol) server that lets AI assistants post and interact across social media platforms.

Supported Platforms

| Platform | Tools | | --------- | ---------------------------------------------------------------------------------------------------------------------- | | Telegram | Send message, get channel info, forward message, pin message, get channel administrators, edit message, delete message | | Twitter/X | Send tweet, reply to tweet, like tweet, delete tweet, get user info, search tweets | | Discord | Send message, get messages | | WhatsApp | Send message | | Facebook | Create post, get posts | | Instagram | Create post, get posts | | Slack | Send message, get messages, list channels | | LinkedIn | Get profile, create post, get posts, like post, add comment, search people | | Reddit | Submit post, get posts, comment, vote, search, get user info | | Threads | Get profile, create post, reply, get posts, delete post | | Bluesky | Get profile, create post, reply, get posts, delete post, like post, search posts | | Mastodon | Get profile, create post, reply, search posts, boost post, favourite post, delete post | | TikTok | Query creator info, get user info, post video, photo post, get post status | | YouTube | Get channel info, search videos, get video info, list channel videos, get comments, post comment, update video | | Pinterest | Get boards, create board, create pin, get pin, get board pins, delete pin | | Email | Send email, send bulk email (drivers: SMTP, SendGrid, Mailgun) |

Quick Start

Run directly with npx — no install required:

npx social-mcp

Or install globally:

npm install -g social-mcp
social-mcp

MCP Client Configuration

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "social-mcp": {
      "command": "npx",
      "args": ["social-mcp"],
      "env": {
        "TELEGRAM_BOT_TOKEN": "your_token",
        "TWITTER_APP_KEY": "your_key",
        "TWITTER_APP_SECRET": "your_secret",
        "TWITTER_ACCESS_TOKEN": "your_token",
        "TWITTER_ACCESS_SECRET": "your_secret",
        "DISCORD_BOT_TOKEN": "your_token",
        "WHATSAPP_ACCESS_TOKEN": "your_token",
        "WHATSAPP_PHONE_NUMBER_ID": "your_id",
        "FACEBOOK_ACCESS_TOKEN": "your_token",
        "INSTAGRAM_ACCESS_TOKEN": "your_token",
        "SLACK_BOT_TOKEN": "your_token",
        "LINKEDIN_ACCESS_TOKEN": "your_token",
        "REDDIT_CLIENT_ID": "your_client_id",
        "REDDIT_CLIENT_SECRET": "your_client_secret",
        "REDDIT_USERNAME": "your_username",
        "REDDIT_PASSWORD": "your_password",
        "THREADS_ACCESS_TOKEN": "your_token",
        "THREADS_USER_ID": "your_user_id",
        "BLUESKY_IDENTIFIER": "your_handle",
        "BLUESKY_APP_PASSWORD": "your_app_password",
        "MASTODON_ACCESS_TOKEN": "your_token",
        "MASTODON_INSTANCE_URL": "https://mastodon.social",
        "TIKTOK_ACCESS_TOKEN": "your_token",
        "YOUTUBE_ACCESS_TOKEN": "your_token",
        "PINTEREST_ACCESS_TOKEN": "your_token",
        "MAIL_MAILER": "smtp",
        "MAIL_FROM_ADDRESS": "[email protected]",
        "MAIL_FROM_NAME": "Your Name",
        "MAIL_HOST": "smtp.gmail.com",
        "MAIL_PORT": "587",
        "MAIL_USERNAME": "[email protected]",
        "MAIL_PASSWORD": "your_password",
        "MAIL_ENCRYPTION": "tls"
      }
    }
  }
}

Cursor / VS Code (via MCP extension)

{
  "mcp": {
    "servers": {
      "social-mcp": {
        "command": "npx",
        "args": ["social-mcp"],
        "env": { "...": "same env vars as above" }
      }
    }
  }
}

Only include env vars for the platforms you actually use — unconfigured platforms are reported at startup but do not prevent the server from running.

Environment Variables

Copy example.env to .env and fill in the credentials for the platforms you want to use.

Telegram

| Variable | Description | | -------------------- | --------------------------------------------------- | | TELEGRAM_BOT_TOKEN | Bot token from @BotFather |

Twitter / X

| Variable | Description | | ----------------------- | -------------------------------------------------------------------------- | | TWITTER_APP_KEY | API key from the Twitter Developer Portal | | TWITTER_APP_SECRET | API secret | | TWITTER_ACCESS_TOKEN | Access token (OAuth 1.0a, Read & Write) | | TWITTER_ACCESS_SECRET | Access token secret |

Discord

| Variable | Description | | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | DISCORD_BOT_TOKEN | Bot token from the Discord Developer Portal — bot must have Send Messages and Read Message History permissions |

WhatsApp Business

| Variable | Description | | -------------------------- | --------------------------------------- | | WHATSAPP_ACCESS_TOKEN | Access token from Meta for Developers | | WHATSAPP_PHONE_NUMBER_ID | Phone Number ID from WhatsApp API Setup |

Facebook

| Variable | Description | | ----------------------- | ---------------------------------------------- | | FACEBOOK_ACCESS_TOKEN | Page Access Token from Meta Graph API Explorer |

Instagram

| Variable | Description | | ------------------------ | -------------------------------------------- | | INSTAGRAM_ACCESS_TOKEN | Token with instagram_content_publish scope |

Slack

| Variable | Description | | ----------------- | ------------------------------------------------------------------------------------------------------------------------------ | | SLACK_BOT_TOKEN | Bot token from api.slack.com — requires chat:write, channels:history, channels:read scopes |

LinkedIn

| Variable | Description | | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | LINKEDIN_ACCESS_TOKEN | OAuth 2.0 access token from the LinkedIn Developer Portal — requires r_liteprofile, w_member_social scopes |

Reddit

| Variable | Description | | ---------------------- | ---------------------------------------------------------------------------------------------------------- | | REDDIT_CLIENT_ID | App client ID from reddit.com/prefs/apps (create a "script" type app) | | REDDIT_CLIENT_SECRET | App client secret | | REDDIT_USERNAME | Reddit account username | | REDDIT_PASSWORD | Reddit account password |

Threads

| Variable | Description | | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | THREADS_ACCESS_TOKEN | OAuth 2.0 access token from the Meta for Developers — requires threads_basic, threads_content_publish scopes | | THREADS_USER_ID | Your Threads user ID (returned from the Threads API /me endpoint) |

Bluesky

| Variable | Description | | ---------------------- | ------------------------------------------------------------------------------------------------------------- | | BLUESKY_IDENTIFIER | Your Bluesky handle (e.g., user.bsky.social) or email address | | BLUESKY_APP_PASSWORD | App-specific password generated at bsky.app/settings/app-passwords | | BLUESKY_SERVICE | (Optional) Bluesky service URL (defaults to https://bsky.social) |

Mastodon

| Variable | Description | | ----------------------- | ----------------------------------------------------------------------------- | | MASTODON_ACCESS_TOKEN | OAuth 2.0 access token from your Mastodon instance | | MASTODON_INSTANCE_URL | (Optional) Your Mastodon instance URL (defaults to https://mastodon.social) |

TikTok

| Variable | Description | | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | TIKTOK_ACCESS_TOKEN | OAuth 2.0 access token from the TikTok for Developers — requires user.info.basic, video.publish, video.upload scopes |

YouTube

| Variable | Description | | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | YOUTUBE_ACCESS_TOKEN | OAuth 2.0 access token from the Google Cloud Console — requires https://www.googleapis.com/auth/youtube scope |

Pinterest

| Variable | Description | | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | PINTEREST_ACCESS_TOKEN | OAuth 2.0 Bearer token from the Pinterest Developer Portal — requires boards:read boards:write pins:read pins:write scopes |

Email

Email uses a Laravel-style driver system. Env vars are optional — credentials can also be passed inline per tool call (see Per-org / Multi-account Usage).

Set MAIL_MAILER to select your provider and only configure the variables for the driver you choose.

| Variable | Description | | -------------------- | ---------------------------------------------------------------------- | | MAIL_MAILER | Mail driver: smtp, sendgrid, or mailgun (default: smtp) | | MAIL_FROM_ADDRESS | Sender email address (required for all drivers) | | MAIL_FROM_NAME | Sender display name (optional) |

SMTP (MAIL_MAILER=smtp)

| Variable | Description | | ----------------- | -------------------------------------------------------------------------- | | MAIL_HOST | SMTP server hostname (e.g. smtp.gmail.com, smtp.mailgun.org) | | MAIL_PORT | SMTP port (default: 587) | | MAIL_USERNAME | SMTP authentication username | | MAIL_PASSWORD | SMTP authentication password | | MAIL_ENCRYPTION | Connection security: tls (default), ssl, or none |

SMTP verification: On startup, social-mcp calls transporter.verify() against your SMTP server. A misconfigured host or wrong password shows [!!] in the startup log rather than failing silently on the first send.

SendGrid (MAIL_MAILER=sendgrid)

| Variable | Description | | ------------------ | -------------------------------------------------------------------------------------- | | SENDGRID_API_KEY | API key from the SendGrid dashboard |

Mailgun (MAIL_MAILER=mailgun)

| Variable | Description | | ----------------- | -------------------------------------------------------------------------------------------- | | MAILGUN_API_KEY | API key from Mailgun account settings | | MAILGUN_DOMAIN | Your Mailgun sending domain (e.g. mg.yourdomain.com) |

Available Tools

Telegram

• TELEGRAM_SEND_MESSAGE — Send a message to a chat or channel (chatId, text)
• TELEGRAM_GET_CHANNEL_INFO — Get channel metadata (channelId)
• TELEGRAM_FORWARD_MESSAGE — Forward a message between chats (fromChatId, toChatId, messageId)
• TELEGRAM_PIN_MESSAGE — Pin a message in a chat (chatId, messageId)
• TELEGRAM_GET_CHANNEL_MEMBERS — List channel administrators (channelId, limit)
• TELEGRAM_EDIT_MESSAGE — Edit the text of a message (chatId, messageId, text)
• TELEGRAM_DELETE_MESSAGE — Delete a message (chatId, messageId)

Twitter / X

• SEND_TWEET — Post a tweet (text, max 280 chars)
• REPLY_TWEET — Reply to a tweet (tweetId, text)
• LIKE_TWEET — Like a tweet (tweetId)
• DELETE_TWEET — Delete a tweet (tweetId)
• GET_TWITTER_USER_INFO — Get a user's profile and metrics (username)
• SEARCH_TWEETS — Search recent tweets (query, maxResults)

Discord

• SEND_DISCORD_MESSAGE — Send a message to a channel (channelId, content)
• GET_DISCORD_MESSAGES — Retrieve recent messages from a channel (channelId, limit)

WhatsApp

• SEND_WHATSAPP_MESSAGE — Send a message to a phone number in E.164 format (to, text)

Note: WhatsApp message retrieval requires webhook setup and cannot be polled via the API.

Facebook

• CREATE_FACEBOOK_POST — Create a post on a Facebook page (pageId, message)
• GET_FACEBOOK_POSTS — Retrieve recent posts from a page (pageId, limit)

Instagram

• CREATE_INSTAGRAM_POST — Publish an image post (userId, imageUrl, caption)
• GET_INSTAGRAM_POSTS — Retrieve recent posts from an account (userId, limit)

Slack

• SEND_SLACK_MESSAGE — Send a message to a channel (channelId, text)
• GET_SLACK_MESSAGES — Retrieve recent messages from a channel (channelId, limit)
• LIST_SLACK_CHANNELS — List public channels in the workspace (limit)

LinkedIn

• GET_LINKEDIN_PROFILE — Get the authenticated user's profile information
• CREATE_LINKEDIN_POST — Create a UGC post (authorUrn, text, visibility)
• GET_LINKEDIN_POSTS — Retrieve recent posts by a member or organization (authorUrn, count)
• DELETE_LINKEDIN_POST — Delete a UGC post (ugcPostUrn)
• LIKE_LINKEDIN_POST — Like a post (actorUrn, ugcPostUrn)
• ADD_LINKEDIN_COMMENT — Comment on a post (actorUrn, ugcPostUrn, text)
• SEARCH_LINKEDIN_PEOPLE — Search for people by keywords (keywords, count)

Note: SEARCH_LINKEDIN_PEOPLE uses the LinkedIn People Search API which requires Partner Program access. Most developer apps will receive a 403. All other tools work with a standard OAuth 2.0 token.

Reddit

• REDDIT_SUBMIT_POST — Submit a text or link post to a subreddit (subreddit, title, kind, text, url)
• REDDIT_GET_POSTS — Get posts from a subreddit (subreddit, sort, limit)
• REDDIT_COMMENT — Comment on a post or reply to a comment (parentId, text)
• REDDIT_VOTE — Upvote, downvote, or remove a vote (id, direction)
• REDDIT_SEARCH — Search Reddit across all or a specific subreddit (query, subreddit, sort, limit)
• REDDIT_GET_USER_INFO — Get public info about a Reddit user (username)

Note: Reddit requires a "script" type app in reddit.com/prefs/apps. The password grant flow is used — 2FA must be disabled on the account.

Threads

• THREADS_GET_PROFILE — Get your Threads profile information
• THREADS_CREATE_POST — Create a new text post (text)
• THREADS_REPLY — Reply to a Threads post (replyToId, text)
• THREADS_GET_POSTS — Get recent posts from your account (limit)
• THREADS_DELETE_POST — Delete a post by ID (mediaId)

Bluesky

• BLUESKY_GET_PROFILE — Get your Bluesky profile information
• BLUESKY_CREATE_POST — Create a new text post (text)
• BLUESKY_REPLY_TO_POST — Reply to a Bluesky post (text, parentUri, parentCid, rootUri, rootCid)
• BLUESKY_GET_POSTS — Get recent posts from your feed (limit)
• BLUESKY_DELETE_POST — Delete a post by URI (uri, cid)
• BLUESKY_LIKE_POST — Like a post (uri, cid)
• BLUESKY_SEARCH_POSTS — Search for posts on Bluesky (query, limit)

Mastodon

• MASTODON_GET_PROFILE — Get your Mastodon profile information
• MASTODON_CREATE_POST — Create a new post (status, inReplyToId optional, visibility)
• MASTODON_REPLY_TO_POST — Reply to a Mastodon post (status, inReplyToId)
• MASTODON_SEARCH_POSTS — Search for posts on your instance (query, limit)
• MASTODON_BOOST_POST — Reblog/boost a post (statusId)
• MASTODON_FAVOURITE_POST — Favorite/like a post (statusId)
• MASTODON_DELETE_POST — Delete a post (statusId)

TikTok

• TIKTOK_QUERY_CREATOR_INFO — Query creator info including posting permissions and privacy options
• TIKTOK_GET_USER_INFO — Get TikTok account profile and stats
• TIKTOK_DIRECT_POST_VIDEO — Post a video by URL (videoUrl, title, privacyLevel, ...)
• TIKTOK_PHOTO_POST — Create a photo/carousel post (photoUrls, title, description, privacyLevel)
• TIKTOK_GET_POST_STATUS — Check the publishing status of a video or photo post (publishId)

Note: TikTok's Content Posting API requires app approval from TikTok for Developers. Videos are pulled from a public URL by TikTok's servers rather than uploaded directly.

YouTube

• YOUTUBE_GET_CHANNEL_INFO — Get channel info and stats (channelId optional — omit for your own channel)
• YOUTUBE_SEARCH_VIDEOS — Search YouTube for videos (query, maxResults, pageToken)
• YOUTUBE_GET_VIDEO_INFO — Get detailed info and stats for a video (videoId)
• YOUTUBE_LIST_CHANNEL_VIDEOS — List recent uploads from a channel (channelId, maxResults, pageToken)
• YOUTUBE_GET_COMMENTS — Get top-level comments on a video (videoId, maxResults)
• YOUTUBE_POST_COMMENT — Post a comment on a video (videoId, text)
• YOUTUBE_UPDATE_VIDEO — Update a video's title, description, and tags (videoId, title, description, tags, categoryId)

Note: YouTube requires an OAuth 2.0 access token with the https://www.googleapis.com/auth/youtube scope. Enable the YouTube Data API v3 in your Google Cloud Console project. Video uploads are not supported via this API — use the YouTube Studio or resumable upload flow directly.

Pinterest

• PINTEREST_GET_BOARDS — List all boards on your Pinterest account (pageSize)
• PINTEREST_CREATE_BOARD — Create a new board (name, description)
• PINTEREST_CREATE_PIN — Create a pin on a board (boardId, title, description, imageUrl, link)
• PINTEREST_GET_PIN — Get details of a specific pin (pinId)
• PINTEREST_GET_BOARD_PINS — List all pins on a board (boardId, pageSize)
• PINTEREST_DELETE_PIN — Delete a pin by ID (pinId)

Email

• EMAIL_SEND — Send an email to a single recipient (to, subject, text, html; plus optional inline credentials — see below)
• EMAIL_SEND_BULK — Send the same email to multiple recipients (recipients, subject, text, html; plus optional inline credentials)

The active mail driver is selected by MAIL_MAILER. Switching providers requires only changing that one variable — no code changes needed. Credentials can also be passed inline per call for multi-account / per-org use cases.

Per-org / Multi-account Usage

Both email tools accept inline credentials as optional parameters. When provided, they take full priority over env vars — a fresh, isolated EmailService is created for that call. This enables per-organization or per-user email accounts without any env var changes.

Example — SMTP:

{
  "mailer": "smtp",
  "fromAddress": "[email protected]",
  "fromName": "Acme Corp",
  "smtpHost": "smtp.gmail.com",
  "smtpPort": 587,
  "smtpUsername": "[email protected]",
  "smtpPassword": "app-password",
  "smtpEncryption": "tls",
  "to": "[email protected]",
  "subject": "Hello",
  "text": "Hi there!"
}

Example — SendGrid:

{
  "mailer": "sendgrid",
  "fromAddress": "[email protected]",
  "sendgridApiKey": "SG.xxxx",
  "recipients": ["[email protected]", "[email protected]"],
  "subject": "Newsletter",
  "text": "Plain text body",
  "html": "<p>HTML body</p>"
}

Example — Mailgun:

{
  "mailer": "mailgun",
  "fromAddress": "[email protected]",
  "mailgunApiKey": "key-xxxx",
  "mailgunDomain": "mg.acme.com",
  "to": "[email protected]",
  "subject": "Hello",
  "text": "Hi there!"
}

When mailer and fromAddress are omitted, the tool falls back to the env var configuration (MAIL_MAILER, MAIL_FROM_ADDRESS, etc.).

Development

pnpm install
pnpm run build      # compile TypeScript
pnpm run clean      # remove dist/
pnpm run watch      # watch mode
pnpm run test       # run tests
pnpm run lint       # lint with Biome
pnpm run format     # format with Biome

For a clean rebuild:

pnpm run clean && pnpm run build

Support

If you find this project useful, consider supporting its development:

License

MIT