{"id":31534098,"url":"https://github.com/cameronrye/activitypub-mcp","last_synced_at":"2026-02-03T06:08:12.358Z","repository":{"id":316425638,"uuid":"1060935870","full_name":"cameronrye/activitypub-mcp","owner":"cameronrye","description":"A comprehensive Model Context Protocol (MCP) server that enables LLMs like Claude to explore and interact with the existing Fediverse through standardized MCP tools, resources, and prompts.","archived":false,"fork":false,"pushed_at":"2025-10-02T21:30:35.000Z","size":1090,"stargazers_count":2,"open_issues_count":8,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-10-02T23:30:17.194Z","etag":null,"topics":["activitypub","fedify","fediverse","mcp","mcp-server","webfinger"],"latest_commit_sha":null,"homepage":"https://cameronrye.github.io/activitypub-mcp/","language":"Astro","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/cameronrye.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":".github/SECURITY.md","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":"2025-09-20T22:33:47.000Z","updated_at":"2025-10-02T21:30:39.000Z","dependencies_parsed_at":"2025-09-24T15:36:13.929Z","dependency_job_id":null,"html_url":"https://github.com/cameronrye/activitypub-mcp","commit_stats":null,"previous_names":["cameronrye/activitypub-mcp"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/cameronrye/activitypub-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cameronrye%2Factivitypub-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cameronrye%2Factivitypub-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cameronrye%2Factivitypub-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cameronrye%2Factivitypub-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cameronrye","download_url":"https://codeload.github.com/cameronrye/activitypub-mcp/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cameronrye%2Factivitypub-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278266896,"owners_count":25958733,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-04T02:00:05.491Z","response_time":63,"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":["activitypub","fedify","fediverse","mcp","mcp-server","webfinger"],"created_at":"2025-10-04T05:17:20.195Z","updated_at":"2026-02-03T06:08:12.350Z","avatar_url":"https://github.com/cameronrye.png","language":"Astro","funding_links":[],"categories":["Search \u0026 Extraction","📦 Other"],"sub_categories":["Data APIs"],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"public/logo.svg\" alt=\"ActivityPub MCP Logo\" width=\"200\" /\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003eActivityPub MCP Server\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eFediverse Client for LLMs\u003c/strong\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  A comprehensive \u003cstrong\u003eModel Context Protocol (MCP)\u003c/strong\u003e server that enables LLMs like Claude to \u003cstrong\u003eexplore and interact with the existing Fediverse\u003c/strong\u003e through standardized MCP tools, resources, and prompts.\n\u003c/p\u003e\n\n\u003c!-- Trigger CI --\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://badge.fury.io/js/activitypub-mcp\"\u003e\u003cimg src=\"https://badge.fury.io/js/activitypub-mcp.svg\" alt=\"npm version\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://opensource.org/licenses/MIT\"\u003e\u003cimg src=\"https://img.shields.io/badge/License-MIT-yellow.svg\" alt=\"License: MIT\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.typescriptlang.org/\"\u003e\u003cimg src=\"https://img.shields.io/badge/TypeScript-007ACC?logo=typescript\u0026logoColor=white\" alt=\"TypeScript\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://nodejs.org/\"\u003e\u003cimg src=\"https://img.shields.io/badge/Node.js-18+-339933?logo=node.js\u0026logoColor=white\" alt=\"Node.js\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://modelcontextprotocol.io/\"\u003e\u003cimg src=\"https://img.shields.io/badge/MCP-Compatible-blueviolet\" alt=\"MCP Compatible\" /\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/cameronrye/activitypub-mcp/actions\"\u003e\u003cimg src=\"https://github.com/cameronrye/activitypub-mcp/actions/workflows/ci.yml/badge.svg\" alt=\"CI\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.npmjs.com/package/activitypub-mcp\"\u003e\u003cimg src=\"https://img.shields.io/npm/dm/activitypub-mcp.svg\" alt=\"npm downloads\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/cameronrye/activitypub-mcp\"\u003e\u003cimg src=\"https://img.shields.io/github/stars/cameronrye/activitypub-mcp?style=social\" alt=\"GitHub stars\" /\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n\u003ch2 align=\"center\"\u003eWhat's New in v1.1.0\u003c/h2\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eThe biggest release yet!\u003c/strong\u003e Now with full write capabilities, multi-account support, and enterprise-ready features.\n\u003c/p\u003e\n\n\u003ctable align=\"center\"\u003e\n  \u003ctr\u003e\n    \u003ctd align=\"center\"\u003e\u003cstrong\u003ePost \u0026 Interact\u003c/strong\u003e\u003cbr/\u003eCreate posts, reply, boost, favourite, and bookmark directly from your LLM\u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\u003cstrong\u003eMulti-Account\u003c/strong\u003e\u003cbr/\u003eManage multiple fediverse accounts with secure credential storage\u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\u003cstrong\u003eMedia \u0026 Polls\u003c/strong\u003e\u003cbr/\u003eUpload images with alt text, vote on polls, schedule posts\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd align=\"center\"\u003e\u003cstrong\u003eExport Anywhere\u003c/strong\u003e\u003cbr/\u003eExport timelines, threads, and accounts to JSON, Markdown, or CSV\u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\u003cstrong\u003eHTTP Transport\u003c/strong\u003e\u003cbr/\u003eProduction-ready HTTP/SSE mode for enterprise deployments\u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\u003cstrong\u003e53 Tools\u003c/strong\u003e\u003cbr/\u003e21 read-only + 28 authenticated + 4 export tools\u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"#authenticated-write-tools-v110\"\u003eSee Authenticated Tools\u003c/a\u003e |\n  \u003ca href=\"#content-export-tools-v110\"\u003eSee Export Tools\u003c/a\u003e |\n  \u003ca href=\"CHANGELOG.md\"\u003eFull Changelog\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n## Features\n\n### Core Capabilities\n\n- **Fediverse Client**: Interact with existing ActivityPub servers (Mastodon, Pleroma, Misskey, etc.)\n- **WebFinger Discovery**: Find and discover actors across the fediverse\n- **MCP Protocol**: Complete MCP server with resources, tools, and prompts\n- **LLM-Optimized**: Designed specifically for LLM interaction patterns\n- **TypeScript**: Fully typed with modern TypeScript and ESM\n- **High Performance**: Efficient resource management and caching\n- **Secure**: Built-in security features and input validation\n- **Dual Transport**: Supports both stdio (Claude Desktop) and HTTP transport modes\n\n### Fediverse Interaction Features\n\n- **Remote Actor Discovery**: Find users on any fediverse instance\n- **Timeline Fetching**: Get posts from any user's timeline with pagination support\n- **Trending Content**: Access trending hashtags and posts\n- **Instance Discovery**: Find and explore fediverse instances via live API\n- **Instance Information**: Get detailed info about any server\n- **Search Capabilities**: Search for accounts, hashtags, and posts across instances\n- **Post Threads**: Fetch complete conversation threads with replies\n- **WebFinger Support**: Resolve actor identifiers across the network\n- **Multi-Platform Support**: Works with Mastodon, Pleroma, Misskey, and more\n- **Follower/Following Lists**: Access social connections\n- **Batch Operations**: Fetch multiple actors or posts in a single request\n\n### MCP Features\n\n- **Resources** (10 total): Access remote ActivityPub data (actors, timelines, trending, instance info)\n- **Tools** (53 total): Discover, interact, and create content in the fediverse\n  - 21 read-only tools for discovery and exploration (including unified search)\n  - 28 authenticated tools for posting, interactions, polls, media, and scheduling\n  - 4 export tools for data export in JSON, Markdown, or CSV formats\n- **Prompts** (11 total): Templates for fediverse exploration, content strategy, and community analysis\n- **Monitoring**: Built-in logging, audit trails, and performance metrics\n- **Health Checks**: Server health monitoring and diagnostics\n\n### Authenticated Features (v1.1.0)\n\n- **Multi-Account Support**: Manage multiple fediverse accounts with secure credential storage\n- **Posting Operations**: Create, reply to, and delete posts\n- **Social Interactions**: Boost, favourite, bookmark, follow, mute, and block\n- **Authenticated Timelines**: Access home timeline, notifications, bookmarks, and favourites\n- **Content Export**: Export timelines, threads, and account data in multiple formats\n\n### Security \u0026 Administration\n\n- **Instance Blocklist**: Block specific instances by domain or wildcard pattern\n- **Audit Logging**: Comprehensive logging of all tool invocations and resource access\n- **Content Warnings**: Respect and display content warnings from posts\n- **Rate Limiting**: Protect against abuse with configurable rate limits\n\n## Quick Start\n\n### Prerequisites\n\n- **Node.js 18+** (LTS recommended)\n- **npm** or **yarn** package manager\n- **Git** for cloning the repository\n\n### Cross-Platform Support\n\nThis project works on **Windows**, **macOS**, and **Linux** with automatic platform detection and appropriate script selection.\n\n### One-Click Installation\n\nFor the fastest setup, use our automated installation script:\n\n#### Universal (All Platforms)\n```bash\n# Install directly with npx (recommended)\nnpx activitypub-mcp install\n\n# Or clone and run setup\ngit clone https://github.com/cameronrye/activitypub-mcp.git\ncd activitypub-mcp\nnpm run setup\n```\n\n#### Platform-Specific Installation\n\n**Windows (PowerShell):**\n```powershell\n# Clone and setup\ngit clone https://github.com/cameronrye/activitypub-mcp.git\ncd activitypub-mcp\nnpm run setup:windows\n\n# Or run PowerShell script directly\n.\\scripts\\setup.ps1\n```\n\n**macOS/Linux (Bash):**\n```bash\n# Clone and setup\ngit clone https://github.com/cameronrye/activitypub-mcp.git\ncd activitypub-mcp\nnpm run setup:unix\n\n# Or run bash script directly\nbash scripts/setup.sh\n```\n\n### Manual Installation\n\n1. **Clone and install dependencies**:\n\n```bash\ngit clone https://github.com/cameronrye/activitypub-mcp.git\ncd activitypub-mcp\nnpm install\n```\n\n2. **Configure environment**:\n\n**Windows:**\n```cmd\n# Copy environment template\ncopy .env.example .env\n\n# Edit configuration (optional)\nnotepad .env\n```\n\n**macOS/Linux:**\n```bash\n# Copy environment template\ncp .env.example .env\n\n# Edit configuration (optional)\nnano .env\n```\n\n3. **Start the MCP server**:\n\n```bash\n# Start the MCP server (no local ActivityPub server needed)\nnpm run mcp\n```\n\n### Testing the Setup\n\n**Test MCP server** with MCP Inspector:\n\n```bash\n# Install MCP Inspector\nnpm install -g @modelcontextprotocol/inspector\n\n# Connect to the MCP server\nmcp-inspector\n```\n\n### Claude Desktop Integration\n\nTo use this MCP server with Claude Desktop:\n\n1. **Locate your Claude Desktop config file**:\n   - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`\n   - **Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n2. **Add the server configuration**:\n\n```json\n{\n  \"mcpServers\": {\n    \"activitypub\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"activitypub-mcp\"]\n    }\n  }\n}\n```\n\n3. **Restart Claude Desktop** to load the new server.\n\n## Documentation\n\n### Quick Reference\n\nFor detailed usage instructions, examples, and troubleshooting, see:\n\n- **[Usage Guide](docs/guides/USAGE_GUIDE.md)** - Comprehensive usage documentation\n- **[Examples](docs/guides/EXAMPLES.md)** - Practical examples and integration patterns\n- **[API Reference](#api-reference)** - Complete API documentation (below)\n\n### API Reference\n\n### MCP Resources\n\nResources provide read-only access to fediverse data from any ActivityPub server. All resources return JSON data unless otherwise specified.\n\n#### Server Info Resource\n\nGet information about the ActivityPub MCP server:\n\n```uri\nactivitypub://server-info\n```\n\n**Parameters:**\n- None required\n\n**Example Response:**\n\n```json\n{\n  \"name\": \"activitypub-mcp\",\n  \"version\": \"1.1.0\",\n  \"description\": \"A Model Context Protocol server for exploring and interacting with the existing Fediverse\",\n  \"capabilities\": {\n    \"resources\": [\"server-info\", \"remote-actor\", \"remote-timeline\", \"remote-followers\", \"remote-following\", \"instance-info\", \"trending\", \"local-timeline\", \"federated-timeline\", \"post-thread\"],\n    \"tools\": {\n      \"discovery\": [\"discover-actor\", \"discover-instances\", \"discover-instances-live\", \"recommend-instances\"],\n      \"content\": [\"fetch-timeline\", \"get-post-thread\", \"search-instance\", \"search-accounts\", \"search-hashtags\", \"search-posts\"],\n      \"timelines\": [\"get-trending-hashtags\", \"get-trending-posts\", \"get-local-timeline\", \"get-federated-timeline\"],\n      \"utility\": [\"convert-url\", \"batch-fetch-actors\", \"batch-fetch-posts\"],\n      \"system\": [\"health-check\", \"performance-metrics\"]\n    },\n    \"prompts\": [\"explore-fediverse\", \"discover-content\", \"compare-instances\", \"compare-accounts\", \"analyze-user-activity\", \"find-experts\", \"summarize-trending\"]\n  },\n  \"features\": {\n    \"auditLogging\": true,\n    \"instanceBlocklist\": true,\n    \"contentWarnings\": true,\n    \"batchOperations\": true\n  }\n}\n```\n\n#### Remote Actor Resource\n\nGet information about any actor in the fediverse:\n\n```uri\nactivitypub://remote-actor/{identifier}\n```\n\n**Parameters:**\n- `identifier` (string): The actor's fediverse handle (e.g., user@mastodon.social)\n\n**Example Response:**\n\n```json\n{\n  \"@context\": [\"https://www.w3.org/ns/activitystreams\"],\n  \"id\": \"https://mastodon.social/users/alice\",\n  \"type\": \"Person\",\n  \"preferredUsername\": \"alice\",\n  \"name\": \"Alice Smith\",\n  \"summary\": \"Software developer passionate about decentralized social networks\",\n  \"inbox\": \"https://mastodon.social/users/alice/inbox\",\n  \"outbox\": \"https://mastodon.social/users/alice/outbox\"\n}\n```\n\n#### Remote Timeline Resource\n\nAccess any actor's timeline/outbox from across the fediverse:\n\n```uri\nactivitypub://remote-timeline/{identifier}\n```\n\n**Parameters:**\n- `identifier` (string): The actor's fediverse handle (e.g., user@mastodon.social)\n\n**Example Response:**\n\n```json\n{\n  \"@context\": \"https://www.w3.org/ns/activitystreams\",\n  \"type\": \"OrderedCollection\",\n  \"id\": \"https://mastodon.social/users/alice/outbox\",\n  \"totalItems\": 42,\n  \"orderedItems\": [...]\n}\n```\n\n#### Instance Info Resource\n\nGet information about any fediverse instance:\n\n```uri\nactivitypub://instance-info/{domain}\n```\n\n**Parameters:**\n- `domain` (string): The instance domain (e.g., mastodon.social)\n\n**Example Response:**\n\n```json\n{\n  \"domain\": \"mastodon.social\",\n  \"software\": \"mastodon\",\n  \"version\": \"4.2.1\",\n  \"description\": \"The original server operated by the Mastodon gGmbH non-profit\",\n  \"registrations\": true,\n  \"stats\": {\n    \"user_count\": 900000,\n    \"status_count\": 50000000\n  }\n}\n```\n\n#### Remote Followers/Following Resources\n\nAccess follower and following lists from any actor:\n\n```uri\nactivitypub://remote-followers/{identifier}\nactivitypub://remote-following/{identifier}\n```\n\n#### Trending Resource (New)\n\nGet trending hashtags and posts from an instance:\n\n```uri\nactivitypub://trending/{domain}\n```\n\n#### Local Timeline Resource (New)\n\nGet the local public timeline from an instance:\n\n```uri\nactivitypub://local-timeline/{domain}\n```\n\n#### Federated Timeline Resource (New)\n\nGet the federated public timeline from an instance:\n\n```uri\nactivitypub://federated-timeline/{domain}\n```\n\n#### Post Thread Resource (New)\n\nGet a post and its full conversation thread:\n\n```uri\nactivitypub://post-thread/{postUrl}\n```\n\n### MCP Tools\n\nTools enable LLMs to discover and interact with the fediverse. All tools return structured responses with success/error information.\n\n#### Discover Actor\n\nDiscover and get information about any actor in the fediverse:\n\n```json\n{\n  \"name\": \"discover-actor\",\n  \"arguments\": {\n    \"identifier\": \"user@mastodon.social\"\n  }\n}\n```\n\n**Parameters:**\n- `identifier` (string, required): Fediverse handle (e.g., user@mastodon.social)\n\n#### Fetch Timeline\n\nFetch posts from any actor's timeline with pagination support:\n\n```json\n{\n  \"name\": \"fetch-timeline\",\n  \"arguments\": {\n    \"identifier\": \"user@mastodon.social\",\n    \"limit\": 20,\n    \"cursor\": null,\n    \"maxId\": null\n  }\n}\n```\n\n**Parameters:**\n\n- `identifier` (string, required): Fediverse handle\n- `limit` (number, optional): Number of posts to fetch (1-50, default: 20)\n- `cursor` (string, optional): Pagination cursor from previous response\n- `minId` (string, optional): Return results newer than this ID\n- `maxId` (string, optional): Return results older than this ID\n- `sinceId` (string, optional): Return results since this ID\n\n#### Get Instance Info\n\nGet detailed information about any fediverse instance:\n\n```json\n{\n  \"name\": \"get-instance-info\",\n  \"arguments\": {\n    \"domain\": \"mastodon.social\"\n  }\n}\n```\n\n**Parameters:**\n- `domain` (string, required): Instance domain\n\n#### Search Instance\n\nSearch for content on a specific fediverse instance:\n\n```json\n{\n  \"name\": \"search-instance\",\n  \"arguments\": {\n    \"domain\": \"mastodon.social\",\n    \"query\": \"typescript\",\n    \"type\": \"accounts\"\n  }\n}\n```\n\n**Parameters:**\n- `domain` (string, required): Instance domain to search\n- `query` (string, required): Search query\n- `type` (string, optional): Type of content (\"accounts\", \"statuses\", \"hashtags\")\n\n#### Discover Instances\n\nFind popular fediverse instances by category or topic:\n\n```json\n{\n  \"name\": \"discover-instances\",\n  \"arguments\": {\n    \"category\": \"mastodon\",\n    \"topic\": \"technology\",\n    \"size\": \"medium\"\n  }\n}\n```\n\n**Parameters:**\n- `category` (string, optional): Software type (\"mastodon\", \"pleroma\", \"misskey\", etc.)\n- `topic` (string, optional): Topic or interest to search for\n- `size` (string, optional): Instance size (\"small\", \"medium\", \"large\")\n- `region` (string, optional): Geographic region or language\n- `beginnerFriendly` (boolean, optional): Show only beginner-friendly instances\n\n#### Recommend Instances\n\nGet personalized instance recommendations based on interests:\n\n```json\n{\n  \"name\": \"recommend-instances\",\n  \"arguments\": {\n    \"interests\": [\"technology\", \"programming\", \"open source\"]\n  }\n}\n```\n\n**Parameters:**\n\n- `interests` (array, required): List of your interests or topics\n\n#### Discover Instances Live (New)\n\nReal-time instance discovery via instances.social API:\n\n```json\n{\n  \"name\": \"discover-instances-live\",\n  \"arguments\": {\n    \"software\": \"mastodon\",\n    \"language\": \"en\",\n    \"minUsers\": 1000,\n    \"openRegistrations\": true,\n    \"limit\": 20\n  }\n}\n```\n\n**Parameters:**\n\n- `software` (enum, optional): Filter by software type (mastodon, pleroma, misskey, pixelfed, lemmy, peertube, any)\n- `language` (string, optional): Filter by language code (e.g., \"en\", \"de\", \"ja\")\n- `minUsers` (number, optional): Minimum number of users\n- `maxUsers` (number, optional): Maximum number of users\n- `openRegistrations` (boolean, optional): Only show instances with open registrations\n- `sortBy` (enum, optional): Sort by \"users\", \"statuses\", \"connections\", or \"name\"\n- `limit` (number, optional): Number of results (default: 20)\n\n#### Get Trending Hashtags (New)\n\nGet currently trending hashtags on an instance:\n\n```json\n{\n  \"name\": \"get-trending-hashtags\",\n  \"arguments\": {\n    \"domain\": \"mastodon.social\",\n    \"limit\": 20\n  }\n}\n```\n\n#### Get Trending Posts (New)\n\nGet currently trending posts on an instance:\n\n```json\n{\n  \"name\": \"get-trending-posts\",\n  \"arguments\": {\n    \"domain\": \"mastodon.social\",\n    \"limit\": 20\n  }\n}\n```\n\n#### Get Local Timeline (New)\n\nGet the local public timeline from an instance:\n\n```json\n{\n  \"name\": \"get-local-timeline\",\n  \"arguments\": {\n    \"domain\": \"mastodon.social\",\n    \"limit\": 20\n  }\n}\n```\n\n#### Get Federated Timeline (New)\n\nGet the federated public timeline from an instance:\n\n```json\n{\n  \"name\": \"get-federated-timeline\",\n  \"arguments\": {\n    \"domain\": \"mastodon.social\",\n    \"limit\": 20\n  }\n}\n```\n\n#### Get Post Thread (New)\n\nFetch a post and its full conversation thread:\n\n```json\n{\n  \"name\": \"get-post-thread\",\n  \"arguments\": {\n    \"postUrl\": \"https://mastodon.social/@user/123456789\",\n    \"depth\": 2,\n    \"maxReplies\": 50\n  }\n}\n```\n\n#### Search Accounts (New)\n\nSearch for accounts on an instance:\n\n```json\n{\n  \"name\": \"search-accounts\",\n  \"arguments\": {\n    \"domain\": \"mastodon.social\",\n    \"query\": \"developer\",\n    \"limit\": 20\n  }\n}\n```\n\n#### Search Hashtags (New)\n\nSearch for hashtags on an instance:\n\n```json\n{\n  \"name\": \"search-hashtags\",\n  \"arguments\": {\n    \"domain\": \"mastodon.social\",\n    \"query\": \"programming\",\n    \"limit\": 20\n  }\n}\n```\n\n#### Search Posts (New)\n\nSearch for posts on an instance:\n\n```json\n{\n  \"name\": \"search-posts\",\n  \"arguments\": {\n    \"domain\": \"mastodon.social\",\n    \"query\": \"typescript\",\n    \"limit\": 20\n  }\n}\n```\n\n#### Batch Fetch Actors (New)\n\nFetch multiple actors in a single request:\n\n```json\n{\n  \"name\": \"batch-fetch-actors\",\n  \"arguments\": {\n    \"identifiers\": [\"user1@mastodon.social\", \"user2@fosstodon.org\"]\n  }\n}\n```\n\n#### Batch Fetch Posts (New)\n\nFetch multiple posts in a single request:\n\n```json\n{\n  \"name\": \"batch-fetch-posts\",\n  \"arguments\": {\n    \"urls\": [\"https://mastodon.social/@user/123\", \"https://fosstodon.org/@user/456\"]\n  }\n}\n```\n\n#### Health Check\n\nCheck the health status of the MCP server:\n\n```json\n{\n  \"name\": \"health-check\",\n  \"arguments\": {}\n}\n```\n\n**Parameters:**\n- None required\n\n#### Performance Metrics\n\nGet performance metrics for the MCP server:\n\n```json\n{\n  \"name\": \"performance-metrics\",\n  \"arguments\": {\n    \"operation\": \"discover-actor\"\n  }\n}\n```\n\n**Parameters:**\n- `operation` (string, optional): Specific operation to get metrics for\n\n### MCP Prompts\n\n#### Explore Fediverse\n```json\n{\n  \"name\": \"explore-fediverse\",\n  \"arguments\": {\n    \"interests\": \"technology and programming\",\n    \"instanceType\": \"mastodon\"\n  }\n}\n```\n\n#### Compare Instances\n```json\n{\n  \"name\": \"compare-instances\",\n  \"arguments\": {\n    \"instances\": \"mastodon.social, fosstodon.org, hachyderm.io\",\n    \"criteria\": \"community size and focus\"\n  }\n}\n```\n\n#### Discover Content\n\n```json\n{\n  \"name\": \"discover-content\",\n  \"arguments\": {\n    \"topic\": \"artificial intelligence\",\n    \"contentType\": \"people\"\n  }\n}\n```\n\n#### Compare Accounts (New)\n\n```json\n{\n  \"name\": \"compare-accounts\",\n  \"arguments\": {\n    \"accounts\": \"user1@mastodon.social, user2@fosstodon.org\",\n    \"aspects\": \"posting frequency, topics, engagement\"\n  }\n}\n```\n\n#### Analyze User Activity (New)\n\n```json\n{\n  \"name\": \"analyze-user-activity\",\n  \"arguments\": {\n    \"identifier\": \"user@mastodon.social\",\n    \"depth\": \"standard\"\n  }\n}\n```\n\n#### Find Experts (New)\n\n```json\n{\n  \"name\": \"find-experts\",\n  \"arguments\": {\n    \"topic\": \"machine learning\",\n    \"instances\": \"mastodon.social, fosstodon.org\"\n  }\n}\n```\n\n#### Summarize Trending (New)\n\n```json\n{\n  \"name\": \"summarize-trending\",\n  \"arguments\": {\n    \"instances\": \"mastodon.social\",\n    \"focus\": \"tech\"\n  }\n}\n```\n\n#### Content Strategy (v1.1.0)\n\nPlan your fediverse content strategy based on trending topics:\n\n```json\n{\n  \"name\": \"content-strategy\",\n  \"arguments\": {\n    \"topics\": \"programming, open source\",\n    \"targetAudience\": \"developers\",\n    \"postingFrequency\": \"several-per-week\"\n  }\n}\n```\n\n#### Community Health (v1.1.0)\n\nAnalyze instance moderation and community health:\n\n```json\n{\n  \"name\": \"community-health\",\n  \"arguments\": {\n    \"instance\": \"fosstodon.org\",\n    \"concerns\": \"moderation, spam\"\n  }\n}\n```\n\n#### Migration Helper (v1.1.0)\n\nGet help planning a migration to a new fediverse instance:\n\n```json\n{\n  \"name\": \"migration-helper\",\n  \"arguments\": {\n    \"currentInstance\": \"mastodon.social\",\n    \"targetInstance\": \"fosstodon.org\",\n    \"priorities\": \"moderation, privacy, community focus\"\n  }\n}\n```\n\n#### Thread Composer (v1.1.0)\n\nHelp compose well-structured threaded posts:\n\n```json\n{\n  \"name\": \"thread-composer\",\n  \"arguments\": {\n    \"topic\": \"Introduction to the Fediverse\",\n    \"keyPoints\": \"What is ActivityPub, Popular instances, Getting started\",\n    \"tone\": \"informative\",\n    \"targetLength\": \"medium\"\n  }\n}\n```\n\n### Authenticated Write Tools (v1.1.0)\n\nThese tools require authentication via environment variables. See [Configuration](#environment-variables) for setup.\n\n#### Account Management\n\n- `list-accounts` - List configured accounts\n- `switch-account` - Switch active account\n- `verify-account` - Verify account credentials\n\n#### Posting Operations\n\n```json\n{\n  \"name\": \"post-status\",\n  \"arguments\": {\n    \"content\": \"Hello Fediverse!\",\n    \"visibility\": \"public\",\n    \"contentWarning\": \"optional CW\"\n  }\n}\n```\n\n- `post-status` - Create a new post\n- `reply-to-post` - Reply to an existing post\n- `delete-post` - Delete your own post\n\n#### Social Interactions\n\n- `boost-post` / `unboost-post` - Boost (reblog) posts\n- `favourite-post` / `unfavourite-post` - Favourite posts\n- `bookmark-post` / `unbookmark-post` - Bookmark posts\n- `follow-account` / `unfollow-account` - Follow/unfollow accounts\n- `mute-account` / `unmute-account` - Mute accounts\n- `block-account` / `unblock-account` - Block accounts\n\n#### Authenticated Timelines\n\n- `get-home-timeline` - Your home timeline\n- `get-notifications` - Your notifications\n- `get-bookmarks` - Your bookmarked posts\n- `get-favourites` - Your favourited posts\n\n#### Unified Search (NEW)\n\nSearch across accounts, posts, and hashtags in a single query:\n\n```json\n{\n  \"name\": \"search\",\n  \"arguments\": {\n    \"domain\": \"mastodon.social\",\n    \"query\": \"typescript programming\",\n    \"type\": \"all\",\n    \"limit\": 20\n  }\n}\n```\n\n**Parameters:**\n\n- `domain` (string, required): Instance domain to search\n- `query` (string, required): Search query\n- `type` (string, optional): \"all\", \"accounts\", \"posts\", or \"hashtags\" (default: \"all\")\n- `limit` (number, optional): Results per type (1-40, default: 20)\n- `resolve` (boolean, optional): Attempt WebFinger lookup for remote accounts\n\n#### Relationship Checking (NEW)\n\nCheck your relationship status with other accounts:\n\n```json\n{\n  \"name\": \"get-relationship\",\n  \"arguments\": {\n    \"accountIds\": [\"12345\", \"67890\"]\n  }\n}\n```\n\n**Parameters:**\n\n- `accountIds` (array, required): Account IDs to check relationship status\n\n**Returns:** Following, followed_by, blocking, muting, and other relationship statuses.\n\n#### Poll Voting (NEW)\n\nVote on polls in posts:\n\n```json\n{\n  \"name\": \"vote-on-poll\",\n  \"arguments\": {\n    \"pollId\": \"123456\",\n    \"choices\": [0, 2]\n  }\n}\n```\n\n**Parameters:**\n\n- `pollId` (string, required): The poll ID to vote on\n- `choices` (array, required): Array of choice indices (0-based)\n\n**Returns:** Updated poll with current results and visual bar chart.\n\n#### Media Upload (NEW)\n\nUpload media files with alt text descriptions:\n\n```json\n{\n  \"name\": \"upload-media\",\n  \"arguments\": {\n    \"filePath\": \"/path/to/image.jpg\",\n    \"description\": \"A beautiful sunset over the ocean\",\n    \"focus\": \"0.0,0.5\"\n  }\n}\n```\n\n**Parameters:**\n\n- `filePath` (string, required): Local file path or URL to upload\n- `description` (string, optional): Alt text for accessibility (recommended)\n- `focus` (string, optional): Focal point as \"x,y\" (-1.0 to 1.0)\n\n**Supported types:** Images (jpg, png, gif, webp), Videos (mp4, webm), Audio (mp3, ogg)\n\n#### Scheduled Posts (NEW)\n\nManage scheduled posts:\n\n```json\n{\n  \"name\": \"get-scheduled-posts\",\n  \"arguments\": {\n    \"limit\": 20\n  }\n}\n```\n\n```json\n{\n  \"name\": \"update-scheduled-post\",\n  \"arguments\": {\n    \"scheduledPostId\": \"123\",\n    \"scheduledAt\": \"2026-02-14T18:00:00.000Z\"\n  }\n}\n```\n\n```json\n{\n  \"name\": \"cancel-scheduled-post\",\n  \"arguments\": {\n    \"scheduledPostId\": \"123\"\n  }\n}\n```\n\n- `get-scheduled-posts` - List all pending scheduled posts\n- `update-scheduled-post` - Change the scheduled time\n- `cancel-scheduled-post` - Cancel a scheduled post\n\n### Content Export Tools (v1.1.0)\n\nExport fediverse content in multiple formats (JSON, Markdown, CSV):\n\n```json\n{\n  \"name\": \"export-timeline\",\n  \"arguments\": {\n    \"identifier\": \"user@mastodon.social\",\n    \"format\": \"markdown\",\n    \"limit\": 50\n  }\n}\n```\n\n- `export-timeline` - Export actor timeline\n- `export-thread` - Export post thread with replies\n- `export-account-info` - Comprehensive account data export\n- `export-hashtag` - Export posts with a specific hashtag\n\n## Architecture\n\n### Project Structure\n\n```\nactivitypub-mcp/\n├── src/                           # Source code\n│   ├── mcp-main.ts                # MCP server entry point\n│   ├── mcp-server.ts              # MCP server implementation\n│   ├── webfinger.ts               # WebFinger discovery client\n│   ├── remote-client.ts           # Remote ActivityPub client\n│   ├── instance-discovery.ts      # Static instance discovery\n│   ├── dynamic-instance-discovery.ts # Live API instance discovery\n│   ├── instance-blocklist.ts      # Instance blocklist manager\n│   ├── audit-logger.ts            # Audit logging infrastructure\n│   ├── health-check.ts            # Health monitoring\n│   ├── performance-monitor.ts     # Performance tracking\n│   ├── config.ts                  # Configuration constants\n│   ├── logging.ts                 # Logging configuration\n│   ├── auth/                      # Authentication (v1.1.0)\n│   │   ├── account-manager.ts     # Multi-account management\n│   │   ├── authenticated-client.ts # Authenticated API client\n│   │   └── index.ts               # Auth module exports\n│   ├── mcp/                       # MCP handlers\n│   │   ├── tools.ts               # Read-only tool implementations\n│   │   ├── tools-write.ts         # Write operation tools (v1.1.0)\n│   │   ├── tools-export.ts        # Export tools (v1.1.0)\n│   │   ├── resources.ts           # Resource implementations\n│   │   └── prompts.ts             # Prompt implementations\n│   └── server/                    # Server infrastructure\n│       ├── http-transport.ts      # HTTP/SSE transport\n│       ├── adaptive-rate-limiter.ts # Per-instance rate limiting (v1.1.0)\n│       └── rate-limiter.ts        # Rate limiting\n├── docs/                          # Documentation\n├── scripts/                       # Installation \u0026 setup scripts\n├── tests/                         # Test files\n│   ├── unit/                      # Unit tests\n│   └── integration/               # Integration tests\n├── dist/                          # Built JavaScript files\n├── package.json                   # Dependencies and scripts\n└── README.md                      # This file\n```\n\n### Technology Stack\n- **[WebFinger](https://tools.ietf.org/rfc/rfc7033.txt)**: Actor discovery across the fediverse\n- **[MCP SDK](https://github.com/modelcontextprotocol/typescript-sdk)**: Model Context Protocol implementation\n- **[ActivityPub](https://www.w3.org/TR/activitypub/)**: Decentralized social networking protocol\n- **[LogTape](https://logtape.org/)**: Structured logging\n- **TypeScript**: Type-safe development\n\n### Communication Flow\n```\nLLM Client ←→ MCP Protocol ←→ Fediverse Client ←→ Remote ActivityPub Servers\n                                     ↓\n                              WebFinger Discovery\n                                     ↓\n                              Remote Data Fetching\n```\n\n## Documentation\n\nComprehensive documentation is available in the `docs/` directory:\n\n- **[Setup \u0026 Installation](docs/setup/)** - Configuration and installation guides\n- **[User Guides](docs/guides/)** - Usage examples and tutorials\n- **[Development](docs/development/)** - Development setup and best practices\n- **[Specifications](docs/specifications/)** - ActivityPub and protocol specifications\n\nSee the [Documentation Index](docs/README.md) for a complete overview.\n\n## Development\n\n### Available Scripts\n- `npm run mcp` - Start MCP server\n- `npm run mcp:dev` - Start MCP server in watch mode\n- `npm run test` - Run tests\n- `npm run build` - Build TypeScript\n\n### Environment Variables\n\nCreate a `.env` file:\n\n```env\n# MCP Server configuration\nMCP_SERVER_NAME=activitypub-mcp\nMCP_SERVER_VERSION=1.1.0\n\n# Transport configuration (stdio or http)\nMCP_TRANSPORT_MODE=stdio\nMCP_HTTP_PORT=3000\nMCP_HTTP_HOST=127.0.0.1\nMCP_HTTP_CORS_ENABLED=false\n\n# Rate limiting\nRATE_LIMIT_ENABLED=true\nRATE_LIMIT_MAX=100\nRATE_LIMIT_WINDOW=900000\n\n# Logging\nLOG_LEVEL=info\n\n# Audit logging\nAUDIT_LOG_ENABLED=true\nAUDIT_LOG_MAX_ENTRIES=10000\n\n# Instance blocklist (comma-separated domains)\nBLOCKED_INSTANCES=\nINSTANCE_BLOCKING_ENABLED=true\n\n# Dynamic instance discovery\nINSTANCES_SOCIAL_TOKEN=\nDYNAMIC_INSTANCE_CACHE_TTL=3600000\n\n# Content warnings\nRESPECT_CONTENT_WARNINGS=true\nSHOW_CONTENT_WARNINGS=true\n\n# Authentication (for write operations - v1.1.0)\nACTIVITYPUB_DEFAULT_INSTANCE=mastodon.social\nACTIVITYPUB_DEFAULT_TOKEN=your-oauth-access-token\nACTIVITYPUB_DEFAULT_USERNAME=your-username\n\n# Multi-account configuration (JSON format)\n# ACTIVITYPUB_ACCOUNTS='[{\"id\":\"work\",\"instance\":\"fosstodon.org\",\"token\":\"token1\",\"username\":\"work_account\"},{\"id\":\"personal\",\"instance\":\"mastodon.social\",\"token\":\"token2\",\"username\":\"personal_account\"}]'\n```\n\n### HTTP Transport Mode\n\nFor production deployments, you can run the server in HTTP mode:\n\n```bash\n# Start with HTTP transport\nMCP_TRANSPORT_MODE=http MCP_HTTP_PORT=8080 npm run mcp\n\n# The server exposes:\n# - /mcp    - MCP protocol endpoint\n# - /health - Health check endpoint\n# - /metrics - Performance metrics\n# - /       - Server info\n```\n\n### Testing\n```bash\n# Test MCP server with inspector\nmcp-inspector\n\n# Test fediverse interactions\nnpm run test\n\n# Manual testing with specific actors\n# Use the discover-actor tool to test WebFinger discovery\n```\n\n## Cross-Platform Compatibility\n\nThis project is designed to work seamlessly across different operating systems:\n\n### Supported Platforms\n- **Windows 10/11** (PowerShell, Command Prompt, Git Bash)\n- **macOS** (Bash, Zsh)\n- **Linux** (Bash, most distributions)\n\n### Platform-Specific Features\n- **Automatic script detection**: npm scripts automatically choose the right script for your platform\n- **Native path handling**: Proper configuration paths for each platform\n- **Shell compatibility**: Both PowerShell (.ps1) and Bash (.sh) scripts provided\n\n### Installation Methods by Platform\n\n| Platform | Recommended Method | Alternative Methods |\n|----------|-------------------|-------------------|\n| Windows | `npm run setup` | `.\\scripts\\setup.ps1` or `npm run setup:windows` |\n| macOS | `npm run setup` | `bash scripts/setup.sh` or `npm run setup:unix` |\n| Linux | `npm run setup` | `bash scripts/setup.sh` or `npm run setup:unix` |\n\n### Troubleshooting Platform Issues\n\n**Windows PowerShell Execution Policy:**\n```powershell\n# If you get execution policy errors, run:\nSet-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser\n```\n\n**Windows Git Bash:**\n```bash\n# Git Bash users can use Unix-style commands:\nnpm run setup:unix\n```\n\n**Linux/macOS Permissions:**\n```bash\n# If you get permission errors, make scripts executable:\nchmod +x scripts/*.sh\n```\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch: `git checkout -b feature/amazing-feature`\n3. Commit changes: `git commit -m 'Add amazing feature'`\n4. Push to branch: `git push origin feature/amazing-feature`\n5. Open a Pull Request\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Acknowledgments\n\n- [Fedify](https://fedify.dev/) - ActivityPub server framework\n- [Model Context Protocol](https://modelcontextprotocol.io/) - LLM integration standard\n- [ActivityPub](https://www.w3.org/TR/activitypub/) - W3C decentralized social networking protocol\n\n## Links\n\n- [ActivityPub Specification](https://www.w3.org/TR/activitypub/)\n- [Model Context Protocol](https://modelcontextprotocol.io/)\n- [Fedify Documentation](https://fedify.dev/)\n- [Fediverse](https://fediverse.info/)\n\n---\n\nMade with ❤️ by [Cameron Rye](https://rye.dev/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcameronrye%2Factivitypub-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcameronrye%2Factivitypub-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcameronrye%2Factivitypub-mcp/lists"}