What can you do with this server?

With this server, you can interact with Mastodon by creating and managing toots with various customizable options: * Create and publish text content as toots * Customize visibility (public, unlisted, private, or direct) * Mark content as sensitive with a boolean parameter * Add spoiler warnings/text before toot content * Attach media files (images, videos, audio) * Provide alt text for media attachments * Schedule toots for future posting using ISO 8601 datetime format

Which integrations are available for this server?

Used for secure credential management to store and retrieve Mastodon API tokens, ensuring secure access to Mastodon accounts without hardcoding credentials. Provides tools for posting content to [Mastodon](/mcp/servers/integrations/mastodon), including creating toots with customizable visibility and content warnings, uploading and attaching media files (images, videos, audio), and adding alt text to media attachments.

Mastodon MCP

A Model Context Protocol server that provides tools for interacting with Mastodon. Currently supports creating toots with optional media attachments.

Features

Create toots with customizable visibility and content warnings
Upload and attach media files (images, videos, audio)
Add alt text/descriptions to media attachments
Schedule toots for a future time
Secure credential management using environment variables or 1Password CLI

Related MCP server: MCP Filesystem Server

Prerequisites

Node.js 18+
pnpm
A Mastodon account and API access token
Optionally, 1Password CLI (op) installed and configured if using 1Password for credential management.

Installation

# Clone the repository git clone [repository-url] cd mastodon-mcp # Install dependencies pnpm install # Build the project pnpm build

Configuration

The tool requires a Mastodon API token. You can provide this token in one of the following ways:

Environment Variable (Recommended for simplicity): Set the MASTODON_ACCESS_TOKEN environment variable:
export MASTODON_ACCESS_TOKEN="your_mastodon_api_token"
1Password: Store your token at:
- op://Personal/Floss.Social Key/notesPlain

You can optionally set the Mastodon instance URL via environment variable:

export MASTODON_INSTANCE_URL="https://your.instance.social"

If not set, it defaults to https://floss.social.

Usage

Start the MCP server:

pnpm start

The server exposes a single tool mastodon_create_toot with the following parameters:

content (required): The text content of your toot
visibility: One of "public", "unlisted", "private", or "direct" (default: "public")
sensitive: Boolean flag for sensitive content (default: false)
spoiler_text: Warning text shown before the content (default: "")
media_file: Path to a media file to attach
media_description: Alt text/description for the attached media
scheduled_at: Optional ISO 8601 datetime to schedule the toot for a future time (e.g., "2024-07-04T10:00:00-07:00")

Example Usage with MCP Inspector

Start the inspector:

npx @modelcontextprotocol/inspector node dist/mcp-server.js

Open http://localhost:5173 in your browser
Use the tool with parameters like:

{ "content": "Hello from MCP!", "visibility": "public", "media_file": "/path/to/image.jpg", "media_description": "A beautiful sunset", "scheduled_at": "2025-01-01T12:00:00Z" }

Development

# Run in development mode with auto-reloading pnpm dev # Build the project pnpm build # Run the built server pnpm start

Security

No credentials are hardcoded in the codebase
API tokens can be securely managed via environment variables or retrieved from 1Password.
API responses are git-ignored to prevent accidental credential leaks