Which integrations are available for this server?

Provides tools for interacting with Mastodon instances, enabling AI assistants to read timelines, post and manage statuses, follow/unfollow accounts, search, and handle notifications, lists, polls, and media.

How do I use mastodon-mcp-server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@mastodon-mcp-server show me my home timeline" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

mastodon-mcp-server

by VitexSoftware

Overview Schema Related Servers Score Discussions

Python

Remote

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

Variable	Required	Default	Description
`MASTODON_INSTANCE`	yes	—	Mastodon instance URL (e.g. `https://mastodon.social` or just `mastodon.social`)
`MASTODON_ACCESS_TOKEN`	yes	—	OAuth access token
`READ_ONLY`	no	`false`	Disable all write operations
`MASTODON_MCP_TRANSPORT`	no	`stdio`	Transport: `stdio` or `streamable-http`
`MASTODON_MCP_HOST`	no	`127.0.0.1`	HTTP transport bind address
`MASTODON_MCP_PORT`	no	`8000`	HTTP transport port
`MASTODON_MCP_STATELESS_HTTP`	no	`false`	Disable HTTP session state
`DEBUG`	no	`false`	Enable verbose logging

Getting an Access Token

Go to your Mastodon instance → Preferences → Development → New application
Grant required scopes: read, write, follow
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: false)
  DEBUG                      Enable verbose logging (default: false)

Available Tools

Instance

Tool	Description
`instance_info`	Instance name, description, version, rules

Accounts

Tool	Description
`account_verify`	Own profile
`account_get`	Account by numeric ID
`account_search`	Search accounts by username or display name
`account_statuses`	Posts by an account
`account_followers` / `account_following`	Social graph
`account_follow` / `account_unfollow`	Follow management
`account_block` / `account_unblock`	Block management
`account_mute` / `account_unmute`	Mute management
`account_relationships`	Relationship to one or more accounts
`account_update`	Update own display name, bio, locked status

Timelines

Tool	Description
`timeline_home`	Home timeline (followed accounts)
`timeline_local`	Local instance public timeline
`timeline_public`	Federated public timeline
`timeline_hashtag`	Statuses with a specific hashtag

Statuses

Tool	Description
`status_get`	Single status by ID
`status_context`	Thread ancestors and descendants
`status_post`	Post a new status (supports CW, visibility, media, polls)
`status_delete`	Delete own status
`status_favourite` / `status_unfavourite`	Favourite management
`status_reblog` / `status_unreblog`	Boost management
`status_bookmark` / `status_unbookmark`	Bookmark management
`status_favourited_by` / `status_reblogged_by`	Who engaged with a status

Notifications

Tool	Description
`notifications_get`	List notifications (filterable by type)
`notification_dismiss`	Dismiss a single notification
`notifications_clear`	Clear all notifications

Search & Discovery

Tool	Description
`search`	Search accounts, statuses, and hashtags
`trending_tags`	Trending hashtags
`trending_statuses`	Trending statuses
`trending_links`	Trending links/articles
`directory`	Browse the instance profile directory

Collections

Tool	Description
`favourites`	Own favourited statuses
`bookmarks`	Own bookmarked statuses
`mutes`	Muted accounts
`blocks`	Blocked accounts

Lists

Tool	Description
`lists_get`	All lists
`list_accounts`	Accounts in a list
`list_create` / `list_delete`	Create/delete lists
`list_accounts_add` / `list_accounts_delete`	Add/remove list members

Polls

Tool	Description
`poll_vote`	Vote in a poll

Follow Requests

Tool	Description
`follow_requests`	Pending follow requests
`follow_request_authorize` / `follow_request_reject`	Accept/reject requests

Media

Tool	Description
`media_post`	Upload image/video/audio attachment

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):

Tool	Requirement
`status_update`	Edit a status (server 3.5+)
`status_history`	Edit history (server 3.5+)
`status_source`	Plain-text source for editing
`status_translate`	Translate a status (server 4.0+)
`conversations`	Direct-message conversations
`scheduled_statuses`	List scheduled posts
`scheduled_status_update`	Reschedule a post
`scheduled_status_delete`	Cancel a scheduled post
`notifications_unread_count`	Unread notification count

Testing

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

# With live instance
MASTODON_INSTANCE=mastodon.social \
MASTODON_ACCESS_TOKEN=your-token \
python3 scripts/test_server.py

Architecture

The server uses a bundled stdlib-only MCP implementation (mastodon_mcp_server/_mcp.py) so it has no dependency on python3-fastmcp or its deep dependency chain. This makes packaging for Debian/Ubuntu straightforward. The implementation is compatible with the FastMCP decorator API (@mcp.tool()).

License

MIT — Vítězslav Dvořák info@vitexsoftware.cz

This server cannot be installed

license - permissive license

quality - not tested

maintenance

How are these scores calculated?

Resources

GitHub Repository

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Latest Blog Posts

Lightport: Open-Sourcing Glama's AI Gateway
By punkpeye on April 27, 2026.
open source
OpenAI
Tool Definition Quality Score (TDQS)
By punkpeye on April 3, 2026.
mcp
The Hackers Who Tracked My Sleep Cycle
By punkpeye on March 26, 2026.
security

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/VitexSoftware/mastodon-mcp-server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server