mastodon-mcp-cliCAUTION
Mastodon MCP server and CLI for Claude Code, Codex and AI agents. 76 tools for posting, editing, threads, timelines, search, lists, notifications and following, across any instance.
Overview
From the repository's own README, as read at the audited commit. Badges and raw HTML are left out.
[](https://www.npmjs.com/package/@thenavidm/mastodon-mcp-cli) [](./LICENSE) [](https://youtube.com/@thenavidm?sub_confirmation=1) [](https://x.com/thenavidm) [](https://linkedin.com/in/thenavidm)
Mastodon MCP server and CLI for Claude Code, Codex and AI agents. 76 tools for posting, editing, threads, timelines, search, lists, notifications and following, across any instance.
One install gives you both surfaces, the same 76 tools under the same names, reading one array of tool definitions so neither can drift from the other.
Setup is one command. Mastodon has no central developer portal, so this registers its own application on your instance and signs you in.
Instance limits are read from the instance, so character counts and poll options are correct wherever you are.
Built and maintained by Navid Moazzez. Built on Slipway, which turns one definition of each tool into the MCP server and the CLI.
Two ways to use it
Command line
mastodon-cli in your terminal, for scripting, cron, pipes, or just asking a quick question without opening anything:
mastodon-cli # every command, one line each mastodon-cli get-home-timeline --limit 50 # your
bca0c006b647OBSERVED · 2026-10-11Connect
Built from this server's own package name, version and transport as found in its source — not copied from anyone's documentation, so it cannot drift against a page we do not control. Replace the environment placeholders with a token scoped to the least it needs.
claude mcp add mastodon-mcp-cli --env MASTODON_ACCESS_TOKEN=${MASTODON_ACCESS_TOKEN} -- npx -y @thenavidm/[email protected]{
"mcpServers": {
"mastodon-mcp-cli": {
"command": "npx",
"args": [
"-y",
"@thenavidm/[email protected]"
],
"env": {
"MASTODON_ACCESS_TOKEN": "${MASTODON_ACCESS_TOKEN}"
}
}
}
}Exposed tools (51)
35 read · 9 write · 7 destructive. Blast radius: 7 tools can delete or overwrite — an agent that can be talked into calling a tool can be talked into calling this one.
| Tool | Risk | Description |
|---|---|---|
add_to_list | write | Add accounts to a list. You have to already follow an account before you can put it on a list, which is the error people hit here. |
answer_follow_request | read | Approve or reject a pending follow request. Rejecting is silent; they are not told. |
block_account | read | Block an account. This is visible to them, removes any follow in either direction, and hides your posts from them. Reversible, but the follows do not come back. Needs confirm: true. |
block_domain | destructive | Hide every account on an entire instance and remove their followers. This is the blunt instrument for a server that is a persistent problem rather than one account. Needs confirm: true. |
browse_directory | read | Accounts that have opted into being discoverable, newest or most recently active first. Scoped to your own instance unless you ask for the wider network. A way to find people on a network with no recommendation engine. |
cancel_scheduled_status | read | Cancel a status that was scheduled but has not published. |
catch-up | read | Summarise what happened while you were away |
clear_notifications | destructive | Delete all notifications permanently. This is not the same as marking them read, and there is no undo. Needs confirm: true. |
create_list | write | Create a curated list. Add accounts to it with add_to_list. |
delete_list | destructive | Delete a list. The accounts on it are not affected, only the list. Needs confirm: true. |
delete_status | destructive | Delete one of your own statuses. This cannot be undone and it discards every boost, reply and favourite it had. To fix a mistake, prefer edit_status, which keeps all of that. Needs confirm: true. |
dismiss_notification | destructive | Remove a single notification from the list. This is not undoable. |
draft-thread | read | Turn an idea into a thread, without posting it |
find-my-people | read | Find accounts worth following on a topic |
follow_hashtag | write | Follow a hashtag, so every public post carrying it appears in your home timeline. The main way to build a feed on Mastodon. |
get_account | read | Full profile for any account: bio, counts, the metadata fields with their verification state, and whether you follow each other. Accepts @user@instance, a bare local username, or a numeric id. Resolves accounts your instance has never seen before. |
get_announcements | write | Announcements from the people who run your instance: downtime, rule changes, moderation decisions. Worth checking when something stops working. |
get_blocked_domains | read | Whole instances you have blocked. |
get_bookmarks | read | Statuses a connected account has bookmarked. Unlike favourites, bookmarks are private. |
get_boosted_by | read | The accounts that boosted a status, as far as your instance knows. |
get_conversations | read | Direct conversations, newest first, each with its participants and last message. Mastodon direct messages are statuses with visibility |
get_favourited_by | read | The accounts that favourited a status. Federation means this is only who your instance knows about, not necessarily everyone. |
get_favourites | read | Statuses a connected account has favourited, newest first. |
get_follow_requests | read | Accounts waiting for you to approve their follow. Only meaningful on a locked account. |
get_followed_hashtags | write | Hashtags you follow. Following a hashtag puts every public post carrying it into your home timeline, which is how you build a feed on a network with no algorithm. Neither existing Mastodon MCP server exposes this. |
get_followers | read | Accounts that follow a given account. Pages automatically past the 40-per-request ceiling. |
get_following | read | Accounts a given account follows. Pages automatically. |
get_list_members | read | The accounts on one of your lists. |
get_lists | read | Your curated lists. Pass a list id to get_list_timeline to read it, which is the closest thing Mastodon has to a custom feed. |
get_notifications | read | Mentions, boosts, favourites, follows, poll results and edits to posts you interacted with. Filter by type to get only the ones that need an answer: |
get_read_position | read | The last notification and home-timeline entry you marked read, shared across every client on this account. Pass the returned id as since_id to fetch only what is new. |
get_relationships | read | For each account named, whether you follow them, whether they follow you, and whether either of you has muted or blocked the other. One call for a whole list: use this before a bulk follow or unfollow rather than reading each profile. |
get_status | read | A single status by id, with its media, poll, link preview and engagement counts. |
get_suggested_follows | read | Accounts the instance suggests you follow, with the reason for each suggestion. |
get_thread | read | A status together with everything above and below it, nested into the real reply tree. Mastodon returns two flat lists and leaves the structure to you; this rebuilds it. Read this before replying, so the reply lands with context. |
get_trends | read | What is trending on this instance right now: hashtags, statuses, or links. Trends are per instance, not network-wide, so a small themed server shows something completely different from mastodon.social. |
list_accounts | read | Every Mastodon account this server can act as, and which instance each lives on. Mastodon is federated, so an account is a token plus an instance: the same handle on two servers is two different people. Use the handle from here as the |
list_scheduled_statuses | read | Statuses queued with scheduled_at that have not published yet. |
mark_read | read | Record how far you have read, so the next get_notifications with since_id returns only what is new. Syncs to the web app and every other client. Affects only your own view. |
post_thread | write | Publish several statuses as one thread, each replying to the last. Every part is checked against this instance |
remove_from_list | destructive | Remove accounts from a list. They are not unfollowed. |
report | read | Report an account, optionally with specific statuses, to your instance |
reschedule_status | write | Change when a scheduled status will publish. Minimum five minutes ahead. |
search | read | Search for accounts, statuses or hashtags. Pasting a URL here with resolve on is also how you pull in a remote post or profile your instance has never seen. Note that most instances do not full-text search public statuses: a thin result set is usually the instance |
translate_status | read | Translate a status into your language using the instance |
unblock_account | destructive | Remove a block. Any follows the block severed do not come back; both sides have to follow again. |
unblock_domain | read | Lift a domain block. Followers removed by the block are not restored. |
unfollow_hashtag | write | Stop a hashtag |
update_profile | write | Change your display name, bio, or the four metadata fields on your profile. Only the arguments you pass are changed. Public the moment it runs, so it needs confirm: true. |
vote_poll | read | Vote in a poll by option index, counting from zero. A vote cannot be changed or taken back, so it needs confirm: true. |
whoami | read | Authenticate against the instance and return the live profile. Use this to confirm a token still works, or when the user says |
Trust audit
CAUTIONgrade B · trust 89/100 Install with care. The audit found things worth knowing before you trust its output.
| Layer | What it checks | Result |
|---|---|---|
| L0 | Provenance & inventory | PASS |
| L1 | Static analysis of the code | WARN |
| L2 | Instruction surface (what it tells the agent) | PASS |
| L3 | Class-specific surface | WARN |
| L4 | Behavioural (sandbox) | SKIPPED |
What the source does
- Filesystem
- declared (1 observation(s))
- Network
- declared (7 observation(s))
- Shell
- none-observed
- Dependencies
- not all pinned
- Secrets in source
- none-found
Findings (9)
const url = new URL(req.url ?? "/", `http://127.0.0.1:${port}`);const redirectUri = oob ? OOB_REDIRECT : `http://127.0.0.1:${port}/callback`;block_domain, clear_notifications, delete_list, delete_status, dismiss_notification, remove_from_list, unblock_account
.mcpbignore
vi.stubEnv("MASTODON_URL", "http://127.0.0.1:9");const family = "👨👩👧👦";
@thenavidm/slipway, zod, @types/node, ajv, typescript, vitest
Node 22 or newer. Scripts keep working for success, usage errors and missing setup; a script that treated exit 1 as "unknown command" or "read-only" should read 2. Over MCP, expect an approval prompt
- **An access token reaches your whole account.** It can post, delete, follow and block as you. Revoke it at `https://your-instance/oauth/authorized_applications`.
Gates applied: no_behavioural_pass.
bca0c006b647full audit observations/trust-audit/mcp-server/thenavidm__mastodon-mcp-cli.json · Report an issue / request a re-scanAudit history
Every audit this server has had. A grade with a past is a grade somebody is still checking.
| Date | Source | Verdict | Grade | Score | Change |
|---|---|---|---|---|---|
| 2026-10-11 | bca0c006b647 | CAUTION | B | 89 | first audit |
Questions
What is the mastodon-mcp-cli MCP server?
Mastodon MCP server and CLI for Claude Code, Codex and AI agents. 76 tools for posting, editing, threads, timelines, search, lists, notifications and following, across any instance.
What tools does mastodon-mcp-cli expose?
51 in total: 35 read-only, 9 that write, and 7 that can delete or overwrite (block_domain, clear_notifications, delete_list, delete_status, dismiss_notification). Every one is listed on this page with its risk.
Is mastodon-mcp-cli safe to connect to an agent?
With care. The audit graded it B (89/100) and found 9 things worth knowing before you trust this server, listed below with the exact line each was found on. Separately from the audit: 7 of its tools can destroy data, so scope the token you give it to what you actually need.
What credentials does mastodon-mcp-cli need?
It reads MASTODON_ACCESS_TOKEN from the environment. Give it a token scoped to the least it needs — an agent that can be talked into calling a tool can be talked into calling it with your credentials.
How current is this page?
The grade is for one exact copy of the source (bca0c006b647), read on 2026-10-11. The repository is watched and re-audited when it changes.