README.md•2.94 kB
# Mastodon MCP
A [Model Context Protocol](https://github.com/thefocus/modelcontextprotocol) 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
```bash
# 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:
1. **Environment Variable (Recommended for simplicity)**:
Set the `MASTODON_ACCESS_TOKEN` environment variable:
```bash
export MASTODON_ACCESS_TOKEN="your_mastodon_api_token"
```
2. **1Password**: Store your token at:
- `op://Personal/Floss.Social Key/notesPlain`
You can optionally set the Mastodon instance URL via environment variable:
```bash
export MASTODON_INSTANCE_URL="https://your.instance.social"
```
If not set, it defaults to `https://floss.social`.
## Usage
Start the MCP server:
```bash
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
1. Start the inspector:
```bash
npx @modelcontextprotocol/inspector node dist/mcp-server.js
```
2. Open http://localhost:5173 in your browser
3. Use the tool with parameters like:
```json
{
"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
```bash
# 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
