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
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_TOKENenvironment 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 tootvisibility: 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 attachmedia_description: Alt text/description for the attached mediascheduled_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
License
ISC