Mastodon MCP Server & CLI

What is the Mastodon MCP server & CLI?

The Mastodon MCP server & CLI is a free, open source program that lets AI agents act on Mastodon for you, in two 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 your instance.

The CLI is the same program as commands. mastodon-cli get-home-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.

In an AI OS, the layer that connects your AI to your context, your data and your tools, a server like this is how your AI reaches Mastodon. I explain how the parts fit together in how to build an AI operating system, and here's how I use AI myself.

What can you ask it?

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

Try asking
Post this, and put a content warning on it.
There's a typo in Tuesday's post. Fix it without losing the boosts.
What did my timeline talk about in the last 12 hours?
Find people posting about local-first software and tell me who's worth following.
Make a list called "rust people" and put everyone I follow who posts about Rust on it.
Turn these notes into a thread. My instance allows 11,000 characters, so check before you split it.

The second one shows why this is useful. Mastodon lets you edit a published post and keeps its boosts, replies and favorites, so fixing a typo doesn't mean starting over.

It works well next to my Bluesky MCP server and Threads MCP server, so your AI can post the same update to Bluesky and share it on Threads in the same chat. Every server I've made is on my MCP servers page.

For the posts themselves, my free Mastodon character counter and Mastodon bio generator help too.

How to install the Mastodon MCP server

Pick your app in the box at the top of this page. You log in once in a terminal, then add the server to your app with a single command or a pasted block. Nothing about your account goes in the app's config.

Windsurf, Zed and Cline take the same server, though they don't have a tab in the box yet. Follow the box's Cursor tab, and put its block here instead:

Set up your Mastodon account

Mastodon has no central developer portal, because every instance is its own server. So the login does the setup for you, on your instance.

npx -y @thenavidm/mastodon-mcp-cli login mastodon.social

Behind that one command, the login registers itself as an app on your instance, catches the answer on your own computer and checks the token. It doesn't ask for push notifications, because nothing here uses them.

Or let your AI set it up

Paste this into Claude Code, Codex or any agent that can run commands:

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

1. Ask me which instance my account is on, e.g. mastodon.social. Do not guess.
2. Run: npx -y @thenavidm/mastodon-mcp-cli login <instance>
   It opens my browser and waits. Tell me to approve the request there, and wait for it to finish. It asks for read, write and follow; that is correct. If there is no browser available, re-run it with --oob and I will paste the code back to you.
3. Register the server with my MCP client. For Claude Code that is:
     claude mcp add mastodon -- npx -y @thenavidm/mastodon-mcp-cli
   No environment variables: step 2 already stored the token.
4. Run: npx -y @thenavidm/mastodon-mcp-cli doctor
   Show me the output. Pay attention to the line about scopes: if it says the account cannot post, the token is read-only and step 2 needs redoing.
5. Tell me to restart the client. Do not post anything.

If I have more than one account, repeat step 2 per account and per instance.

It stops at step 2 and waits, because only you can approve the request in your browser.

Other ways to log in

With no browser, login mastodon.social --oob prints the address and takes a pasted code. If you already made an app on your instance by hand, login mastodon.social --token=YOUR_ACCESS_TOKEN stores it.

If you make that app yourself, tick read, write and follow, and copy "Your access token", not the client secret.

Check that it works

Run the doctor. It reports your instance's real limits, checks the token and checks what the token is allowed to do.

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

That last check matters most. A read-only token passes everything else, then fails on the first post with an error that never mentions why.

In Claude Code, /mcp also shows whether the Mastodon server is connected. It's one of the Claude Code commands worth knowing.

Use the Mastodon CLI

The CLI is the same 76 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 post_status runs as mastodon-cli post-status.

npm install -g @thenavidm/mastodon-mcp-cli
mastodon-cli
mastodon-cli get-home-timeline --limit 50
mastodon-cli search --q "model context protocol"
mastodon-cli post-status --status "Shipped." --confirm

The bare mastodon-cli lists every command, mastodon-cli which <words> finds the command for a task, and mastodon-cli <command> --help shows what a command takes. Posting, editing, deleting and blocking need --confirm, the terminal's version of your approval.

mastodon-cli install <app> adds the server to Claude Code, Codex, Claude Desktop, Cursor, VS Code or Gemini CLI, in each app's own format.

These are the flags you'll use most:

A script can branch on the exit code:

MCP server or CLI: which one?

Both are the same program with the same 76 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 Mastodon 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 Mastodon 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 140 tokens.

When the whole conversation is about Mastodon, 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

59% 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 Mastodon. In Claude Code that's the /mcp panel, and every AI app has its own switch. MASTODON_READ_ONLY=1 cuts it to the 39 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 October 5, 2026 in Claude Code 2.1.286 with Claude Opus 5.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.

What makes Mastodon different

Mastodon isn't one website. Thousands of independent instances talk to each other, and yours decides your limits, what it can show you and which servers it connects to.

A post that seems not to exist may just not have reached your instance yet. Searching for its link with resolve on makes your instance go and fetch it.

Search is usually not full text, because most instances only index your own posts and ones you interacted with. A thin result is the instance's choice, not a bad search.

Timelines have no algorithm, so hashtags, trends, lists and the directory are how you find people. Following a hashtag puts every public post with it into your home timeline.

The server works on Pleroma, Akkoma, GoToSocial and other software that speaks the same API. get_instance_info tells you which one your instance runs, and the doctor warns you when edits or trends may be missing.

Every Mastodon tool

The tables below list all 76 tools, grouped the way the repo groups them. Of these, 39 only read, and 37 change something on your account.

Posting and editing

Timelines

Favorites, boosts and polls

Search and hashtags

Follows, mutes and blocks

Notifications and lists

Accounts and your instance

Is the Mastodon MCP server safe?

A post is public the moment it lands, and deleting it doesn't pull it back off the instances that already have it. So 11 tools ask first. They're the ones marked "Asks first" in the tool tables above.

When your AI calls one of them, the call needs a yes first. Where you use it decides who gives it:

• Claude Code (2.1.246 and later) asks you before every call, in every one of its permission modes.
• An app that can show forms asks you in a form.
• Any other app takes your AI's confirm: true as the yes, so tell your AI to check with you first.
• An agent with no person to ask needs MASTODON_CONFIRM=model, so its confirm: true counts in every app.
• In a terminal, you add --confirm to the command.

If the answer is no, nothing reaches Mastodon.

vote_poll asks because a Mastodon vote can't be changed. report asks because it goes to human moderators.

Favorites, boosts, follows and mutes don't ask, because each is one call to undo. Asking on every favorite would only train your AI to pass the check without thinking.

Make it read-only

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

MASTODON_ALLOW_DESTRUCTIVE=0 is the middle setting. Favorites and follows still work, and posting and deleting don't.

Keep a log of every write

Set MASTODON_AUDIT_LOG to a file path. The server writes one line per attempted write, allowed or blocked.

Your instance's admin can read your direct messages, and so can the admin at the other end. Mastodon DMs aren't encrypted.

Your data

Nothing goes anywhere but your instance. Your token is stored in ~/.mastodon-mcp/accounts.json, readable only by your user account, and there's no tracking of any kind.

To disconnect, open https://your-instance/oauth/authorized_applications and remove the app, which cuts access right away. mastodon-cli logout <handle> only forgets the token on your computer.

Connect more than one Mastodon account

On Mastodon, an account is a token plus an instance, and a personal account and a project account often live on different instances. Run the login once for each:

mastodon-cli login mastodon.social
mastodon-cli login fosstodon.org

Both are stored. Every tool that acts as you takes an optional account, so you can say which one posts, and list_accounts shows them all.

Mastodon MCP server settings

The login is all most people need. These environment variables cover the rest, 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.