How to Use the Mastodon MCP in Claude Code

Q: How do I add the Mastodon MCP Server to Claude Code?

Run the command claude mcp add --transport http mastodon-mcp -- in your terminal, placing all flags before the server name. Claude Code will save this configuration in your local /.claude.json file.

Run Mastodon from your terminal with Claude Code to automate posts, monitor trends, and manage your Fedi account via CLI.

See Vinkius in Action

Works with every AI agent you already use

…and any MCP-compatible client

MCP Servers - Free for Subscribers

Connect Mastodon MCP to Claude Code

Create your Vinkius account to connect Mastodon to Claude Code and route execution through our secure gateway. The platform manages server hosting, runtime updates, and security layers. Configuration requires no manual server provisioning.

GDPR Free for Subscribers

Setup Mastodon with Claude Code

Ask AI about this MCP

ChatGPT

Claude

Perplexity

Script your Mastodon interactions from the terminal.

Claude Code brings headless automation to your Fedi presence. This MCP Server lets your CLI agent check trending topics using `get_trending_tags` and search for specific discussions with `search` without needing a GUI or browser. You can pipe terminal outputs directly into `post_status` to share build reports, system alerts, or project updates. It turns your social account into an extension of your command-line environment.

Manage your Mastodon MCP Server from the terminal.

Managing blocks and mutes is faster when automated. Use Claude Code to process lists of accounts and run `block_account` or `mute_account` in bulk based on criteria you define in the terminal. You can also keep track of server health using `check_health` and view instance rules with `get_instance_rules`. It is a powerful way for administrators and power users to keep tabs on their home instance.

Automated content curation and bookmarking.

Use your terminal agent to scrape relevant industry news. Claude Code can pull your feed using `get_home_timeline` or target specific hashtags with `get_tag_timeline` to find high-value content. Once it identifies a post worth saving, it executes `bookmark_status` or `favourite_status` to flag it for your review. It makes keeping up with the Fedi efficient and completely scriptable.

Setup guide

Set up Mastodon MCP in Claude Code

Prerequisites

Claude Code CLI installed (npm install -g @anthropic-ai/claude-code)
Active Vinkius subscription with a valid endpoint token

1

Run the add command

Open your terminal and run the command shown on the right. Replace [YOUR_TOKEN_HERE] with your endpoint token from cloud.vinkius.com. Use --scope user to make it available across all projects.
2

Verify the connection

Start a Claude Code session and type /mcp to list connected servers. You should see mastodon-mcp with a green status indicator.
3

Start using tools

Ask Claude Code something like "Check my latest Mastodon transactions." It will automatically discover and invoke the available Mastodon tools.

Terminal

claude mcp add --transport http mastodon-mcp https://edge.vinkius.com/[YOUR_TOKEN_HERE]/mcp

Get your connection token →

Prerequisites

Claude Code CLI installed
Active Vinkius subscription with a valid endpoint token

1

Open the config file

Create or edit .mcp.json in your project root for project-level scope, or ~/.claude.json for user-level scope.
2

Add the Mastodon MCP

Paste the JSON snippet shown on the right into the mcpServers object. Replace [YOUR_TOKEN_HERE] with your endpoint token from cloud.vinkius.com.
3

Restart Claude Code

Start a new Claude Code session. Type /mcp to confirm the server is connected. The tools will be automatically available in your conversation.

.mcp.json

{
  "mcpServers": {
    "mastodon-mcp": {
      "type": "url",
      "url": "https://edge.vinkius.com/[YOUR_TOKEN_HERE]/mcp"
    }
  }
}

Get your connection token →

Independent Platform Disclaimer: Vinkius is an independent platform and is not affiliated with, endorsed by, sponsored by, verified by, or otherwise authorized by Mastodon. All third-party trademarks, logos, and brand names are the property of their respective owners. Their use on this website is strictly for informational purposes to identify service compatibility and interoperability.

Why Choose Vinkius

Vinkius connects your tools to AI with real-time monitoring and automatic cost savings — all from one dashboard.

Connect Mastodon now

Real-time monitoring

Live

visibility into every interaction

Connect your favorite tools to your AI and see exactly what's happening — every request, every response, in real time.

Built-in savings

60%

lower AI costs

Vinkius compresses data between your apps and your AI automatically. Lower bills every month — no configuration required.

Single dashboard

One

place for every integration

Every tool your AI connects to, managed from a single screen. One account, complete control.

Common questions about Mastodon MCP in Claude Code

Run the command `claude mcp add --transport http mastodon-mcp -- ` in your terminal, placing all flags before the server name. Claude Code will save this configuration in your local `~/.claude.json` file.

Yes, you can run Claude Code in headless mode within your deployment scripts. It can use `upload_media` to attach build artifacts and `post_status` to announce successful deployments to your followers automatically using this MCP Server.

Simply ask your terminal agent to search for a tag. It will call `get_tag_timeline` or `search` to retrieve the matching posts and print the formatted results directly to your terminal standard output.

Yes, you can configure the server to point to any Fedi instance. The agent will run `get_instance_info` on startup to verify the API version and ensure compatibility with your specific instance's features.

Your instance credentials and timeline data are stored locally in your `~/.claude.json` file. The CLI agent communicates directly with your Fedi instance over HTTPS, keeping your access tokens and private messages isolated on your local machine.

Use it with your favorite AI tools

Connect this server to Cursor, Claude, VS Code, and more.

OpenAI Agents SDK sdk-python

Google ADK sdk-python

Pydantic AI sdk-python

Vercel AI SDK sdk-typescript