mastodon-mcp

A multi-tenant Model Context Protocol (MCP) server for the Mastodon social network API. Supports both stdio and HTTP streaming transports.

Features

• Multi-tenant: Connect multiple Mastodon accounts across different instances
• Account disambiguation: Automatic account selection for single-account setups; prompts for clarification with multiple accounts
• Dual transport: stdio (for Claude Code, etc.) and HTTP streaming (for web clients)
• Full API coverage: Statuses, timelines, accounts, search, notifications, media, instance info, conversations, lists, and filters
• Secure credential storage: Encrypted JSON file for OAuth tokens
• OAuth flow: Per-instance app registration with out-of-band (OOB) code entry

Installation

npm install
npm run build

Usage

stdio transport (default)

node dist/index.js

HTTP streaming transport

node dist/index.js --transport http --port 3000

With encryption passphrase

node dist/index.js --passphrase "your-secret-passphrase"

Claude Code Configuration

Add to your Claude Code settings.json:

{
  "mcpServers": {
    "mastodon": {
      "command": "node",
      "args": ["/path/to/mastodon-mcp/dist/index.js"]
    }
  }
}

Getting Started

1. Start the server
2. Use mastodon_add_account with your instance URL (e.g., mastodon.social)
3. Visit the authorization URL provided
4. Use mastodon_complete_auth with the authorization code

Available Tools

Account Management

• mastodon_add_account - Start OAuth flow to add an account
• mastodon_complete_auth - Complete OAuth with authorization code
• mastodon_list_accounts - List configured accounts
• mastodon_remove_account - Remove an account

Statuses

• mastodon_create_status - Create a toot (with polls, media, scheduling)
• mastodon_get_status / mastodon_delete_status / mastodon_edit_status
• mastodon_boost_status / mastodon_unboost_status
• mastodon_favourite_status / mastodon_unfavourite_status
• mastodon_bookmark_status / mastodon_unbookmark_status
• mastodon_get_status_context
• mastodon_list_scheduled_statuses / mastodon_cancel_scheduled_status

Timelines

• mastodon_get_timeline_home / mastodon_get_timeline_public
• mastodon_get_timeline_hashtag / mastodon_get_timeline_list

Accounts

• mastodon_get_own_account / mastodon_get_account / mastodon_lookup_account
• mastodon_get_account_statuses
• mastodon_follow_account / mastodon_unfollow_account
• mastodon_mute_account / mastodon_unmute_account
• mastodon_block_account / mastodon_unblock_account
• mastodon_get_relationships
• mastodon_get_followers / mastodon_get_following

Search

• mastodon_search - Search accounts, statuses, hashtags

Notifications

• mastodon_get_notifications / mastodon_get_notification
• mastodon_dismiss_notification / mastodon_clear_notifications

Media

• mastodon_upload_media / mastodon_update_media / mastodon_get_media

Instance

• mastodon_get_instance
• mastodon_get_trending_tags / mastodon_get_trending_statuses
• mastodon_get_custom_emojis / mastodon_get_announcements
• mastodon_get_directory

Conversations

• mastodon_get_conversations / mastodon_delete_conversation
• mastodon_mark_conversation_read

Lists

• mastodon_get_lists / mastodon_get_list
• mastodon_create_list / mastodon_update_list / mastodon_delete_list
• mastodon_get_list_accounts / mastodon_add_list_accounts / mastodon_remove_list_accounts

Filters

• mastodon_get_filters / mastodon_get_filter
• mastodon_create_filter / mastodon_update_filter / mastodon_delete_filter

Credential Storage

Credentials are stored in ~/.mastodon-mcp/accounts.json, encrypted with AES-256-GCM. Use the --passphrase flag to set a custom encryption key.

License

MIT