$ npm install @humanwhocodes/crosspostIf you find this useful, please consider supporting my work with a donation.
A utility for posting across multiple social networks at once.
npm install @humanwhocodes/crosspost
The API is split into two parts:
Client class that can be used to post the same message across multiple services.BlueskyStrategyMastodonStrategyTwitterStrategyLinkedInStrategyDiscordStrategyDiscordWebhookStrategyTelegramStrategyDevtoStrategyNostrStrategy (requires Node.js v22+)Each strategy requires its own parameters that are specific to the service. If you only want to post to a particular service, you can just directly use the strategy for that service.
import {
Client,
TwitterStrategy,
MastodonStrategy,
BlueskyStrategy,
LinkedInStrategy,
DiscordStrategy,
DiscordWebhookStrategy,
TelegramStrategy,
DevtoStrategy,
NostrStrategy,
} from "@humanwhocodes/crosspost";
// Note: Use an app password, not your login password!
const bluesky = new BlueskyStrategy({
identifier: "me.you.social",
password: "your-app-password",
host: "you.social", // "bsky.social" for most people
});
// Note: Personal access token is required
const mastodon = new MastodonStrategy({
accessToken: "your-access-token",
host: "mastodon.host",
});
// Note: OAuth app is required
const twitter = new TwitterStrategy({
accessTokenKey: "access-token-key",
accessTokenSecret: "access-token-secret",
apiConsumerKey: "api-consumer-key",
apiConsumerSecret: "api-consumer-secret",
});
// Note: OAuth access token is required
const linkedin = new LinkedInStrategy({
accessToken: "your-access-token",
});
// Note: Bot token and channel ID required
const discord = new DiscordStrategy({
botToken: "your-bot-token",
channelId: "your-channel-id",
});
// Note: Webhook URL required
const discordWebhook = new DiscordWebhookStrategy({
webhookUrl: "your-webhook-url",
});
// Note: Bot token and chat ID required
const telegram = new TelegramStrategy({
botToken: "your-bot-token",
chatId: "your-chat-id",
});
// Note: API key required
const devto = new DevtoStrategy({
apiKey: "your-api-key",
});
// Note: Private key and relays required
const nostr = new NostrStrategy({
privateKey: "your-private-key", // hex or bech32 format
relays: ["wss://relay.example.com", "wss://relay2.example.com"],
});
// create a client that will post to all services
const client = new Client({
strategies: [
bluesky,
mastodon,
twitter,
linkedin,
discord,
discordWebhook,
telegram,
devto,
nostr,
],
});
// post to all services with up to 4 images (must be PNG, JPEG, or GIF)
await client.post("Hello world!", {
images: [
{
data: imageData, // Uint8Array of image data
alt: "Description of the image",
},
],
});
// post to all services with an abort signal
const controller = new AbortController();
await client.post("Hello world!", { signal: controller.signal });
// post to specific services using postTo
await client.postTo([
{
message: "Hello Twitter!",
strategyId: "twitter", // Uses the strategy's id property
},
{
message: "Hello Mastodon and Bluesky!",
strategyId: "mastodon",
images: [
{
data: imageData, // Uint8Array of image data
alt: "Description of the image",
},
],
},
{
message: "Hello Bluesky!",
strategyId: "bluesky",
},
]);
// post to specific services with a signal
await client.postTo(
[
{
message: "Hello Twitter!",
strategyId: "twitter",
},
{
message: "Hello Mastodon!",
strategyId: "mastodon",
},
],
{ signal: controller.signal },
);
Crosspost also has a command line interface to allow for incorporation into CI systems.
Usage: crosspost [options] ["Message to post."]
--twitter, -t Post to Twitter.
--mastodon, -m Post to Mastodon.
--bluesky, -b Post to Bluesky.
--linkedin, -l Post to LinkedIn.
--discord, -d Post to Discord via bot.
--discord-webhook Post to Discord via webhook.
--devto Post to dev.to.
--telegram Post to Telegram.
--slack, -s Post to Slack.
--nostr, -n Post to Nostr.
--mcp Start MCP server.
--file The file to read the message from.
--image The image file to upload with the message.
--image-alt Alt text for the image (default: filename).
--help, -h Show this message.
--version, -v Show version number.
Examples:
# Post a message to multiple services
npx @humanwhocodes/crosspost -t -m -b "Check out this beach!"
# Post a message with an image to multiple services
npx @humanwhocodes/crosspost -t -m -b --image ./photo.jpg --image-alt "A beautiful sunset" "Check out this beach!"
This posts the message "Hello world!" to Twitter, Mastodon, and Bluesky with an attached image. You can choose to post to any combination by specifying the appropriate command line options.
You can also read the message from a file instead of from the command line:
# Post a message to multiple services
npx @humanwhocodes/crosspost -t -m -b -f message.txt
# Post a message with an image to multiple services
npx @humanwhocodes/crosspost -t -m -b -f message.txt -i path/to/image.jpg
Each strategy requires a set of environment variables in order to execute:
TWITTER_ACCESS_TOKEN_KEYTWITTER_ACCESS_TOKEN_SECRETTWITTER_API_CONSUMER_KEYTWITTER_API_CONSUMER_SECRETMASTODON_ACCESS_TOKENMASTODON_HOSTBLUESKY_HOSTBLUESKY_IDENTIFIERBLUESKY_PASSWORDLINKEDIN_ACCESS_TOKENDISCORD_BOT_TOKENDISCORD_CHANNEL_IDDISCORD_WEBHOOK_URLDEVTO_API_KEYTELEGRAM_BOT_TOKENTELEGRAM_CHAT_IDSLACK_TOKENSLACK_CHANNELNOSTR_PRIVATE_KEYNOSTR_RELAYSTip: You can load environment variables from a .env file by setting the environment variable CROSSPOST_DOTENV. Set it to 1 to use .env in the current working directory, or set it to a specific filepath to use a different location.
Crosspost can be run as an MCP (Model Context Protocol) server, which allows it to be used by AI agents:
npx @humanwhocodes/crosspost --mcp -t -m -b
This starts an MCP server that can post to Twitter, Mastodon, and Bluesky. The server provides prompts and tools for posting to all services or individual services. Only the services indicated by the flags are available via the server.
To run the MCP server through the MCP Inspector for debugging purposes, run the following command:
npx run mcp:inspect -- -t -m -b
To use the MCP server with Claude you must have Node.js installed. Then, in Claude Desktop:
Claude will then create a claude_desktop_config.json file. Open it and add the following:
{
"mcpServers": {
"crosspost": {
"command": "npx",
"args": ["@humanwhocodes/crosspost", "-m", "-l", "--mcp"],
"env": {
"LINKEDIN_ACCESS_TOKEN": "abcdefghijklmnop",
"MASTODON_ACCESS_TOKEN": "abcdefghijklmnop",
"MASTODON_HOST": "mastodon.social"
}
}
}
}
This example enables Mastodon and LinkedIn so the env key contains the environment variables necessary to post to those services. You can customize the services by passing different command line arguments as you would using the CLI.
If you'd prefer not to put your environment variables directly into the JSON file, you can create a .env file and use the CROSSPOST_DOTENV environment variable to point to it:
{
"mcpServers": {
"crosspost": {
"command": "npx",
"args": ["@humanwhocodes/crosspost", "-m", "-l", "-t", "--mcp"],
"env": {
"CROSSPOST_DOTENV": "/usr/nzakas/settings/.env"
}
}
}
}
Here are some prompts you can try:
Each strategy uses the service's preferred way of posting messages, so you'll need to follow specific steps in order to enable API access.
To enable posting on Twitter, you'll need to create a free developer account and an OAuth application. Follow these instructions.
Generally speaking, if you are creating an app to automate your own posts, you'll be able to use it for free so long as you're not posting a large number of times per day.
Note: The post uses the terms "app key" and "app secret" whereas the Twitter strategy here uses "API consumer key" and "API consumer secret". They are the same values.
To enable posting to Mastodon, you'll need to create a new application:
write:statuses for your scope. If you want to upload images, check off write:media too.This will generate a client key, client secret, and access token. You only need to use the access token when posting via the API.
Bluesky doesn't require an application for automated posts, only your identifier and an app password. To generate an app password:
Important: Do not use your login password with the API.
To enable posting to LinkedIn, follow these steps:
openid, profile and w_member_social scopes.Important: Tokens automatically expire after two months.
To enable posting to Discord using a bot, you'll need to create a bot and get its token:
To add the bot to your server:
To get your channel ID:
Note: By default your application will only be able to send messages to public channels. To send messages to private channels, you'll have to give your application the necessary permissions.
To enable posting to Discord using a webhook, you'll need to create a webhook and get its URL:
Use the copied webhook URL as the webhookUrl parameter in the DiscordWebhookStrategy configuration.
To enable posting to Dev.to:
Use this API key as the value for the DEVTO_API_KEY environment variable when using the CLI.
The first line of your post will be used as the article title on Dev.to.
To enable posting to Telegram using a bot:
/newbot.4839574812:AAFD39kkdpWt3ywyRZergyOLMaJhac60qc.TELEGRAM_BOT_TOKEN environment variable.For the TELEGRAM_CHAT_ID (required):
@username.TELEGRAM_CHAT_ID environment variable.To enable posting to Slack using a bot:
chat:write - Send messages as the bot userfiles:write - Upload files as the bot user (required for image support)xoxb-. This is your SLACK_TOKEN.To get your channel ID:
C1234567890).#general).Use the bot token as the SLACK_TOKEN environment variable and the channel ID or name as the SLACK_CHANNEL environment variable.
Note: The bot must be added to the channel you want to post to. You can do this by mentioning the bot in the channel (e.g., @your-bot-name) or by using the /invite @your-bot-name command.
Note: Your bot can only send messages to users who have previously messaged the bot or added it to a group.
To enable posting to Nostr relays:
For the NOSTR_PRIVATE_KEY (required):
nsec1.For the NOSTR_RELAYS (required):
wss:// for secure or ws:// for insecure)."wss://relay.damus.io","wss://relay.nostr.band","wss://nos.lol").Nostr posts are "short text notes" (kind 1 events) with a 280 character limit. Images are not supported in Nostr text notes.
Important: Nostr support only works in Node.js v22+.
Security: Keep your private key secure and never share it. Consider using a dedicated key for crossposting rather than your main Nostr identity key.
Copyright 2024-2025 Nicholas C. Zakas
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.