# 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