{"id":49418104,"url":"https://github.com/groupthink-dev/mastodon-blade-mcp","last_synced_at":"2026-04-29T04:06:23.527Z","repository":{"id":350778284,"uuid":"1201200362","full_name":"Groupthink-dev/mastodon-blade-mcp","owner":"Groupthink-dev","description":null,"archived":false,"fork":false,"pushed_at":"2026-04-28T04:23:11.000Z","size":114,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-28T06:27:13.081Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Groupthink-dev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-04T10:51:30.000Z","updated_at":"2026-04-28T04:23:11.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Groupthink-dev/mastodon-blade-mcp","commit_stats":null,"previous_names":["groupthink-dev/mastodon-blade-mcp"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Groupthink-dev/mastodon-blade-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Groupthink-dev%2Fmastodon-blade-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Groupthink-dev%2Fmastodon-blade-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Groupthink-dev%2Fmastodon-blade-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Groupthink-dev%2Fmastodon-blade-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Groupthink-dev","download_url":"https://codeload.github.com/Groupthink-dev/mastodon-blade-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Groupthink-dev%2Fmastodon-blade-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32407176,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-28T19:38:08.556Z","status":"online","status_checked_at":"2026-04-29T02:00:06.602Z","response_time":110,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-04-29T04:06:22.778Z","updated_at":"2026-04-29T04:06:23.513Z","avatar_url":"https://github.com/Groupthink-dev.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Mastodon Blade MCP\n\nA security-first, token-efficient MCP server for Mastodon. 45 tools across timelines, statuses, notifications, search, and social interactions.\n\n## Why another Mastodon MCP?\n\n| | The-Focus-AI/mastodon-mcp | cameronrye/activitypub-mcp | **This** |\n|---|---|---|---|\n| **Tools** | ~4 (minimal) | 53 (ActivityPub-generic) | 45 (Mastodon-targeted) |\n| **Token cost** | Full JSON dumps | Verbose output | Pipe-delimited, HTML-stripped |\n| **Write safety** | None | None | Write gate + confirm gate |\n| **Rate limiting** | None | None | X-RateLimit-* header parsing, adaptive backoff |\n| **Multi-instance** | Single only | Single | Native multi-instance |\n| **Notifications** | None | Basic | Full filtering by type |\n| **Credential safety** | N/A | N/A | Scrubbed from all output |\n\n**This MCP** is designed for agentic platforms that need:\n- **Precise reads** -- query one status, one thread, one hashtag. No full-state dumps.\n- **Safe writes** -- two-tier gating (env var + per-call confirm) for destructive operations.\n- **Multi-instance** -- manage multiple Mastodon servers from a single MCP.\n- **Token efficiency** -- pipe-delimited output, HTML stripping, null-field omission.\n- **Rate limit awareness** -- parses Mastodon headers, warns at thresholds, backs off when exhausted.\n\n## Quick Start\n\n### Install\n\n```bash\n# With uv (recommended)\nuv tool install mastodon-blade-mcp\n\n# Or from source\ngit clone https://github.com/groupthink-dev/mastodon-blade-mcp.git\ncd mastodon-blade-mcp\nmake install\n```\n\n### Configure\n\n```bash\n# Single instance\nexport MASTODON_INSTANCE=\"https://mastodon.social\"\nexport MASTODON_TOKEN=\"your-access-token\"\n\n# Multi-instance\nexport MASTODON_PROVIDERS=\"social,hachyderm\"\nexport MASTODON_SOCIAL_INSTANCE=\"https://mastodon.social\"\nexport MASTODON_SOCIAL_TOKEN=\"token-for-social\"\nexport MASTODON_HACHYDERM_INSTANCE=\"https://hachyderm.io\"\nexport MASTODON_HACHYDERM_TOKEN=\"token-for-hachyderm\"\n\n# Enable posting, favouriting, following (disabled by default)\nexport MASTODON_WRITE_ENABLED=\"true\"\n```\n\nCreate an access token at **Preferences \u003e Development \u003e New Application** on your Mastodon instance.\n\n### Run\n\n```bash\n# stdio (default -- for Claude Code, Claude Desktop)\nmastodon-blade-mcp\n\n# HTTP transport (for remote access)\nMASTODON_MCP_TRANSPORT=http MASTODON_MCP_API_TOKEN=your-secret mastodon-blade-mcp\n```\n\n### Claude Code Integration\n\n```json\n{\n  \"mcpServers\": {\n    \"mastodon\": {\n      \"command\": \"uvx\",\n      \"args\": [\"mastodon-blade-mcp\"],\n      \"env\": {\n        \"MASTODON_INSTANCE\": \"https://mastodon.social\",\n        \"MASTODON_TOKEN\": \"your-token\",\n        \"MASTODON_WRITE_ENABLED\": \"true\"\n      }\n    }\n  }\n}\n```\n\n### Claude Desktop Integration\n\n```json\n{\n  \"mcpServers\": {\n    \"mastodon\": {\n      \"command\": \"uvx\",\n      \"args\": [\"mastodon-blade-mcp\"],\n      \"env\": {\n        \"MASTODON_INSTANCE\": \"https://mastodon.social\",\n        \"MASTODON_TOKEN\": \"your-token\"\n      }\n    }\n  }\n}\n```\n\n## Tools (45)\n\n### Read (25 tools)\n\n| Tool | Description | Token Cost |\n|------|-------------|-----------|\n| `mastodon_info` | Instance info, write gate, rate limit status | Low |\n| `mastodon_verify` | Verify credentials (current user) | Low |\n| `mastodon_timeline_home` | Home timeline (followed accounts) | Medium |\n| `mastodon_timeline_public` | Public/federated timeline | Medium |\n| `mastodon_timeline_local` | Local instance timeline | Medium |\n| `mastodon_timeline_hashtag` | Hashtag timeline | Medium |\n| `mastodon_timeline_list` | List timeline | Medium |\n| `mastodon_status` | Get specific status by ID | Low |\n| `mastodon_context` | Thread context (ancestors + descendants) | Medium |\n| `mastodon_search` | Unified search (accounts/statuses/hashtags) | Medium |\n| `mastodon_account` | Account info by ID | Low |\n| `mastodon_account_statuses` | Account's statuses with filters | Medium |\n| `mastodon_relationships` | Check relationships with accounts | Low |\n| `mastodon_followers` | List followers | Medium |\n| `mastodon_following` | List following | Medium |\n| `mastodon_notifications` | Notifications (filterable by type) | Medium |\n| `mastodon_trending_tags` | Trending hashtags | Low |\n| `mastodon_trending_statuses` | Trending statuses | Medium |\n| `mastodon_trending_links` | Trending links | Low |\n| `mastodon_bookmarks` | Bookmarked statuses | Medium |\n| `mastodon_favourites` | Favourited statuses | Medium |\n| `mastodon_lists` | All lists | Low |\n| `mastodon_list_accounts` | Accounts in a list | Medium |\n| `mastodon_conversations` | DM conversations | Medium |\n| `mastodon_filters` | Active content filters (v2) | Low |\n\n### Write (20 tools -- require `MASTODON_WRITE_ENABLED=true`)\n\n| Tool | Description | Confirm Gate |\n|------|-------------|:---:|\n| `mastodon_post` | Create new status (text, CW, media, schedule) | |\n| `mastodon_reply` | Reply to a status | |\n| `mastodon_edit` | Edit existing status | |\n| `mastodon_delete` | Delete status | Yes |\n| `mastodon_favourite` | Favourite a status | |\n| `mastodon_unfavourite` | Remove favourite | |\n| `mastodon_boost` | Reblog a status | |\n| `mastodon_unboost` | Remove reblog | |\n| `mastodon_bookmark` | Bookmark a status | |\n| `mastodon_unbookmark` | Remove bookmark | |\n| `mastodon_pin` | Pin to profile | |\n| `mastodon_unpin` | Unpin from profile | |\n| `mastodon_follow` | Follow an account | |\n| `mastodon_unfollow` | Unfollow an account | |\n| `mastodon_block` | Block an account | Yes |\n| `mastodon_unblock` | Unblock an account | |\n| `mastodon_mute` | Mute an account (optional duration) | Yes |\n| `mastodon_unmute` | Unmute an account | |\n| `mastodon_dismiss_notification` | Dismiss single notification | |\n| `mastodon_media_upload` | Upload media attachment | |\n\n## Output Format\n\nAll output is pipe-delimited for token efficiency:\n\n```\n# Status\n109876543210 | @user@mastodon.social | 2026-04-04 10:30 | public | Hello world! | fav=5 | boost=2 | reply=1\n\n# Account\n@user@mastodon.social | Test User | followers=100 | following=50 | statuses=200\n\n# Notification\n99999 | mention | @other@mastodon.social | 2026-04-04 11:00 | status=109876543210 | \"@user Hey there!\"\n\n# Search results\n## Accounts (1)\n@user@mastodon.social | Test User | followers=100 | following=50 | statuses=200\n## Hashtags (1)\n#python | uses_7d=42\n\n# Thread context\n## Ancestors (1)\nanc-1 | @parent@mastodon.social | 2026-04-04 09:00 | public | Original post\n## Descendants (2)\ndesc-1 | @reply1@mastodon.social | 2026-04-04 11:00 | public | First reply\ndesc-2 | @reply2@mastodon.social | 2026-04-04 12:00 | public | Second reply\n```\n\n## Security Model\n\n| Layer | Mechanism |\n|-------|-----------|\n| Write gate | `MASTODON_WRITE_ENABLED=true` env var for any mutation |\n| Confirm gate | `confirm=true` parameter for delete, block, mute |\n| Credential scrubbing | Tokens and instance URLs stripped from all error output |\n| Bearer auth | Optional `MASTODON_MCP_API_TOKEN` for HTTP transport (timing-safe comparison) |\n| Rate limiting | X-RateLimit-* header parsing with adaptive backoff |\n| No caching | Credentials read from env at startup, never persisted |\n\n## Multi-Instance Support\n\nTarget a specific instance with the `instance` parameter on any tool:\n\n```\nmastodon_timeline_home instance=\"social\"\nmastodon_timeline_home instance=\"hachyderm\"\n```\n\nOmit `instance` to use the default (first configured) instance.\n\n## Environment Variables\n\n| Variable | Description | Required |\n|----------|-------------|----------|\n| `MASTODON_INSTANCE` | Instance URL (single-instance) | Yes* |\n| `MASTODON_TOKEN` | OAuth access token | Yes* |\n| `MASTODON_PROVIDERS` | Comma-separated provider names | No |\n| `MASTODON_{NAME}_INSTANCE` | Per-provider instance URL | Per-provider |\n| `MASTODON_{NAME}_TOKEN` | Per-provider token | Per-provider |\n| `MASTODON_WRITE_ENABLED` | Enable write operations | No (default: false) |\n| `MASTODON_MCP_TRANSPORT` | `stdio` or `http` | No (default: stdio) |\n| `MASTODON_MCP_HOST` | HTTP bind address | No (default: 127.0.0.1) |\n| `MASTODON_MCP_PORT` | HTTP port | No (default: 8770) |\n| `MASTODON_MCP_API_TOKEN` | Bearer token for HTTP transport | No |\n\n\\* Required if `MASTODON_PROVIDERS` is not set.\n\n## Development\n\n```bash\n# Install with dev deps\nmake install-dev\n\n# Run tests\nmake test\n\n# Coverage report\nmake test-cov\n\n# Lint + format + type check\nmake check\n\n# Run the server\nmake run\n```\n\n## Architecture\n\n```\nsrc/mastodon_blade_mcp/\n├── server.py        -- FastMCP 2.0 server, 45 tool definitions\n├── client.py        -- MastodonClient: httpx async, multi-instance\n├── formatters.py    -- Token-efficient pipe-delimited output, HTML stripping\n├── models.py        -- ProviderConfig, write gate, confirm gate, credential scrubbing\n├── rate_limiter.py  -- X-RateLimit-* header parsing, adaptive backoff\n├── auth.py          -- Bearer token middleware for HTTP transport\n└── __main__.py      -- Entry point\n```\n\n**Dependencies:** `fastmcp`, `httpx`, `pydantic`. No Mastodon.py dependency -- pure HTTP against the Mastodon REST API.\n\n## Sidereal Marketplace\n\nThis MCP conforms to the `social-v1` service contract (20/20 operations):\n- **Required (4/4):** timeline, status, search, notifications\n- **Recommended (6/6):** context, account, trending, bookmarks, favourites, relationships\n- **Optional (4/4):** lists, filters, conversations, instance\n- **Gated (6/6):** post, delete, favourite, boost, follow, block\n\nSee `sidereal-plugin.yaml` for the full plugin manifest.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgroupthink-dev%2Fmastodon-blade-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgroupthink-dev%2Fmastodon-blade-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgroupthink-dev%2Fmastodon-blade-mcp/lists"}