Bluesky MCP Server & CLI

What is the Bluesky MCP server & CLI?

The Bluesky MCP server & CLI is a free, open source program that lets AI agents act on Bluesky for you, in 2 ways. The MCP server is what an AI app like Claude, Codex or Cursor connects to, through MCP (Model Context Protocol), the open standard AI apps use to call outside tools.

You ask in plain language. Your AI picks the right tool, and the server makes the call to Bluesky.

The CLI is the same program as commands. bluesky-cli get-timeline runs the same code your AI runs when you ask about your timeline, whether an agent like Claude Code runs it or you do.

What can you ask it?

Once it's set up, you ask the way you'd ask a person. These are real prompts it handles:

Try asking
Post this, and put the link in a card rather than as bare text.
Turn these notes into a thread. Show me the draft first.
What did my timeline talk about in the last 12 hours?
Read the replies to my Tuesday post and tell me which ones deserve an answer.
Study @someone's last 100 posts and tell me what gets engagement for them, relative to their follower count.
Which of my posts got quoted more than they got reposted?

The last one shows why this is useful. Bluesky counts quotes, reposts and replies separately, and a post quoted more than it's reposted usually means people disagreed.

How to install the Bluesky MCP server

Pick your app in the box at the top of this page. Each one is a single command or a pasted block, and they all run through npx, so there's nothing to install first.

Set up your Bluesky account

Bluesky has app passwords: separate passwords you make for one program and can revoke at any time. Never give the server your real password.

Your handle needs its domain. alice won't resolve, and alice.bsky.social will.

Or let your AI set it up

Your AI can't make the app password for you, but it can walk you through it and do the rest. Paste this into Claude Code, Codex or any agent that can run commands:

Set up the Bluesky MCP server
Set up the Bluesky MCP server for me.

1. Tell me to open https://bsky.app/settings/app-passwords, sign in, click Add App Password, name it "mcp", and paste the xxxx-xxxx-xxxx-xxxx value back to you. You cannot do this part yourself, so stop and wait for it.
2. Ask me for my full Bluesky handle, including the domain, e.g. me.bsky.social.
3. Register the server with my MCP client, passing BLUESKY_IDENTIFIER and BLUESKY_APP_PASSWORD as environment variables. For Claude Code that is:
   claude mcp add bluesky -e BLUESKY_IDENTIFIER=<handle> -e BLUESKY_APP_PASSWORD=<password> -- npx -y @thenavidm/bluesky-mcp-cli
   For any other client, write the equivalent JSON into its MCP config file.
4. Run `npx -y @thenavidm/bluesky-mcp-cli doctor` and show me the output.
5. If every line says ok, tell me to restart the client. If any line says FAIL, tell me what it says and what to do about it. Do not try to guess my password or handle, and do not post anything.

It stops at step 1 and waits, because only you can create the app password.

Check that it works

Run the doctor. It checks the network, then your account, then a real read and a real write, and names the fix for anything that fails.

npx -y @thenavidm/bluesky-mcp-cli doctor

When every line says ok, restart your app and ask it who you are on Bluesky. A FAIL on the write check usually means the app password was mistyped.

Use the Bluesky CLI

The CLI is the same 45 tools as commands. AI agents that run commands, like Claude Code, Codex and OpenCode, use it on their own, and you can type the same commands in a terminal or a script. Every tool name becomes a command with dashes, so create_post runs as bluesky-cli create-post.

npm install -g @thenavidm/bluesky-mcp-cli
bluesky-cli
bluesky-cli get-author-feed --actor navid.me
bluesky-cli search-posts "model context protocol"
bluesky-cli create-post --text "Shipped." --confirm

The bare bluesky-cli lists every command, and bluesky-cli <command> --help shows what a command takes. Posting, deleting and blocking need --confirm, the terminal's version of the check your AI has to pass.

These flags work on every command:

A script can branch on the exit code:

MCP server or CLI: which one?

Both are the same program with the same 45 tools. The difference is when your AI pays for them, in the tokens it reads.

An app that loads every tool up front sends the full list with every message, whether you mention Bluesky or not. Claude Code doesn't by default: its tool search sends only the tool names and the server's instructions, and loads a tool's full definition when your AI reaches for it.

The CLI costs nothing until Bluesky comes up. Then your agent reads its skill file once and runs the commands it needs. With the skill added, Claude Code also lists its one-line description with every message, about 150 tokens.

When the whole conversation is about Bluesky, the gap closes. Then the MCP server is the better experience, because you ask in plain language and your AI never has to look up a command.

Where the MCP server's tokens go

55% of it is MCP writing every tool out as JSON Schema, which any server with this many tools pays. The rest is the wording that lets your AI use each tool without guessing.

How to spend less

In Claude Code, leave tool search on, which it is unless you've set ENABLE_TOOL_SEARCH=false.

Turn the server off when you aren't using Bluesky. In Claude Code that's the /mcp panel, and every AI app has its own switch. BLUESKY_READ_ONLY=1 cuts it to the 30 reading tools.

Or install the CLI and connect the server later, on the days it earns its place. Every tool stays in reach, and the standing cost drops to nothing.

Every number here was measured on September 27, 2026 in Claude Code 2.1.257 with Claude Opus 5. It's the same one-line prompt with and without the server connected, once with tool search off so every tool loads, and once with Claude Code's default. The skill was measured the same way, and other apps and models count tokens a little differently.

Every Bluesky tool

All 45 tools, grouped the way the repo groups them. 30 only read, and 15 change something on your account.

Posting

Reading posts

Search and feeds

Likes, reposts and follows

Profiles and lists

Notifications

Analytics

Accounts

Is the Bluesky MCP server safe?

A post is public the moment it lands, and deleting it doesn't pull it out of feeds that already have it. So 4 tools refuse to run until your AI passes confirm: true. They're the ones marked Asks first in the tool tables above.

Likes, reposts, follows and mutes don't ask first, because each is one click to undo. Asking on every like would only train your AI to pass the check without thinking.

Make it read-only

Set BLUESKY_READ_ONLY=1 and every write disappears from the tool list, leaving 30 reading tools. Your AI can't call a tool it can't see.

BLUESKY_ALLOW_DESTRUCTIVE=0 is the middle setting. Likes and follows still work, and posting, deleting and blocking don't.

Keep a log of every write

Set BLUESKY_AUDIT_LOG to a file path. The server writes one line per attempted write, allowed or blocked, with the time and what it was about to do.

Your data

Nothing goes anywhere but Bluesky. Your app password stays in your app's config or your shell, session tokens stay in memory and are never written to disk, and there's no tracking of any kind.

To disconnect, delete the app password at bsky.app/settings/app-passwords. That cuts access right away, and nothing else about your account changes.

Connect more than one Bluesky account

A personal handle and a brand handle both work from one server, with no restart to switch. Get an app password for each account, then set them together:

export BLUESKY_ACCOUNTS='[{"handle":"you.bsky.social","app_password":"xxxx-xxxx-xxxx-xxxx"},{"handle":"brand.example.com","app_password":"yyyy-yyyy-yyyy-yyyy"}]'
export BLUESKY_DEFAULT_ACCOUNT=you.bsky.social

Every tool that acts as you takes an optional account, so you can say which handle posts. Your AI calls list_accounts when it isn't clear which one you mean.

Bluesky MCP server settings

Every setting is an environment variable, in your app's config or your shell.

Troubleshooting

Run the doctor first. It names the step that failed and the fix.

If the server doesn't show up in your app at all, run the command your app runs, in a terminal, and read the error.