mastodon-mcp-server

mastodon-mcp-server

A comprehensive MCP (Model Context Protocol) server for Mastodon integration. Enables AI assistants and other MCP clients to interact with Mastodon instances — read timelines, post statuses, manage accounts, search, and more.

Features

• Timelines: home, local, public, hashtag
• Statuses: post, delete, favourite, reblog, bookmark
• Accounts: follow, unfollow, block, mute, relationships, profile update
• Notifications: read, dismiss individual or all
• Search: accounts, statuses, hashtags
• Trending: tags, statuses, links
• Lists: create, delete, manage members
• Media: upload attachments
• Polls: vote
• Read-only mode: safe browsing without write access
• STDIO and HTTP transports: works with any MCP-compatible client

Installation

Debian 13+ / Ubuntu 24+

apt install mastodon-mcp-server

pip

pip install mastodon-mcp-server

From source

git clone https://github.com/VitexSoftware/mastodon-mcp-server.git
cd mastodon-mcp-server
pip install -e .

Configuration

Copy .env.example to .env and fill in your credentials:

cp .env.example .env

Getting an Access Token

1. Go to your Mastodon instance → Preferences → Development → New application
2. Grant required scopes: read, write, follow
3. Copy the Your access token value

Client Setup

Claude Code (CLI)

claude mcp add --scope user mastodon /usr/bin/mastodon-mcp \
  -e MASTODON_INSTANCE=mastodon.social \
  -e MASTODON_ACCESS_TOKEN=your-token-here

Claude Desktop

~/.config/claude/claude_desktop_config.json:

{
  "mcpServers": {
    "mastodon": {
      "command": "mastodon-mcp",
      "env": {
        "MASTODON_INSTANCE": "https://mastodon.social",
        "MASTODON_ACCESS_TOKEN": "your-token-here"
      }
    }
  }
}

Warp Terminal

~/.warp/mcp_config.json:

{
  "mcpServers": {
    "mastodon": {
      "command": "/usr/bin/mastodon-mcp",
      "args": [],
      "env": {
        "MASTODON_INSTANCE": "https://mastodon.social",
        "MASTODON_ACCESS_TOKEN": "your-token-here"
      }
    }
  }
}

VSCode (GitHub Copilot / Continue)

~/.config/Code/User/mcp.json:

{
  "servers": {
    "MastodonMCP": {
      "type": "stdio",
      "command": "/usr/bin/mastodon-mcp",
      "args": [],
      "env": {
        "MASTODON_INSTANCE": "https://mastodon.social",
        "MASTODON_ACCESS_TOKEN": "your-token-here"
      }
    }
  }
}

HTTP transport (any MCP client)

MASTODON_MCP_TRANSPORT=streamable-http mastodon-mcp

Usage

usage: mastodon-mcp [-h] [--version]

Model Context Protocol server for Mastodon integration.

options:
  -h, --help  show this help message and exit
  --version   show program's version number and exit

Environment variables:
  MASTODON_INSTANCE          Mastodon instance URL (required)
  MASTODON_ACCESS_TOKEN      OAuth access token (required)
  MASTODON_MCP_TRANSPORT     Transport mode: stdio (default) or streamable-http
  MASTODON_MCP_HOST          HTTP bind address (default: 127.0.0.1)
  MASTODON_MCP_PORT          HTTP port (default: 8000)
  MASTODON_MCP_STATELESS_HTTP  Disable HTTP session state (default: false)
  READ_ONLY                  Restrict to read-only operations (default: true)
  DEBUG                      Enable verbose logging (default: false)

Available Tools

Instance

Accounts

Timelines

Statuses

Notifications

Search & Discovery

Collections

Lists

Polls

Follow Requests

Media

Future Tools (Mastodon.py ≥ 2.x / Mastodon server ≥ 3.5)

The following tools are implemented but commented out in server.py. Uncomment them when your distribution ships python3-mastodon >= 2.0.1 (already available on Debian 13/trixie):

Testing

# Offline (tool registration + helper functions + version check)
python3 scripts/test_server.py

# With live instance (basic connectivity)
MASTODON_INSTANCE=https://mastodon.social \
MASTODON_ACCESS_TOKEN=your-token \
python3 scripts/test_server.py

Live capability scenario

tests/live_capability_scenario.py exercises every registered read-only tool against a real Mastodon instance and verifies that write tools refuse with a clear error when READ_ONLY=true (the default).

# Env-based (recommended)
MASTODON_INSTANCE=https://f.cz \
MASTODON_ACCESS_TOKEN=your-token \
READ_ONLY=true \
  python3 tests/live_capability_scenario.py --json-out /tmp/mastodon-live.json

# Or pass credentials as flags
python3 tests/live_capability_scenario.py \
  --instance https://f.cz \
  --access-token "$MASTODON_ACCESS_TOKEN" \
  --json-out /tmp/mastodon-live.json

What it checks:

• MCP tool catalog registration (callable present for every tool)
• Annotation vs validate_write() consistency (readOnlyHint=False tools must guard writes)
• Every read-only tool against the live API (instance, account, timelines, statuses, search, trending, lists, mutes/blocks, directory, …)
• Every write tool under READ_ONLY=true (must raise / refuse; never mutate)

Exit code is 0 only when every non-skipped check passes. Use --json-out for a machine-readable report. --allow-writes skips the write guards (does not exercise mutating calls).

Architecture

The server is built on FastMCP (python3-fastmcp) and Mastodon.py. Tools are registered with MCP annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint). Write tools call validate_write(), which refuses when READ_ONLY is enabled (default: true).

Citation

This project is built on Mastodon.py. If you use it in academic work, please cite:

@article{Diener2026,
  author  = {Diener, Lorenz and Delcourt, Corentin},
  title   = {Mastodon.py: A Python library for the Mastodon API},
  journal = {Journal of Open Source Software},
  year    = {2026},
  volume  = {11},
  number  = {120},
  pages   = {8946},
  doi     = {10.21105/joss.08946},
  url     = {https://doi.org/10.21105/joss.08946}
}

See Mastodon.py's CITATION.cff for details.

License

MIT — Vítězslav Dvořák [email protected]