Mastodon

🚀 Mastodon MCP Server

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

🚀 Quick Start

The Mastodon MCP Server is a powerful tool that allows seamless interaction with Mastodon. It enables users to create posts, attach media, and manage content with ease.

✨ Features

• Create posts with custom visibility and content warnings.
• Upload and attach media files (images, videos, audio).
• Add alt text/description to media attachments.
• Use 1Password CLI for secure credential management.

📦 Installation

Prerequisites

• Node.js version 18 or higher.
• pnpm tool.
• 1Password CLI (op) installed and configured.
• A Mastodon account and API access token.

Steps

# Clone the repository
git clone [repository-url]
cd mastodon-mcp

# Install dependencies
pnpm install

# Build the project
pnpm build

📚 Documentation

Configuration

This tool requires storing the Mastodon API token in 1Password. Store your token at:

• op://Personal/Floss.Social Key/notesPlain

Optionally, set the Mastodon instance URL via an 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 provides a tool mastodon_create_toot with the following parameters:

• content (required): The text content of the post.
• visibility: One of "public", "unlisted", "private", or "direct" (default: "public").
• sensitive: A boolean flag to mark sensitive content (default: false).
• spoiler_text: A text warning displayed before the content (default: "").
• media_file: The path to the media file to attach.
• media_description: The alt text/description of the attached media.

Example Usage with MCP Inspector

1. Start the inspector:

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

2. Open http://localhost:5173 in your browser.
3. Use the tool with parameters similar to the following:

{
  "content": "Greetings from MCP!",
  "visibility": "public",
  "media_file": "/path/to/image.jpg",
  "media_description": "A beautiful sunset"
}

Development

# Run in development mode with auto-reloading
pnpm dev

# Build the project
pnpm build

# Run the built server
pnpm start

Security

• No hard-coded credentials in the codebase.
• API tokens are securely stored and retrieved from 1Password.
• API responses are ignored by git to prevent accidental credential leakage.

📄 License

ISC