ActivityPub MCP Server

1<p align="center">
2  <img src="public/logo.svg" alt="ActivityPub MCP Logo" width="200" />
3</p>
4 
5<h1 align="center">ActivityPub MCP Server</h1>
6 
7<p align="center">
8  <strong>Fediverse Client for LLMs</strong>
9</p>
10 
11<p align="center">
12  A comprehensive <strong>Model Context Protocol (MCP)</strong> server that enables LLMs like Claude to <strong>explore and interact with the existing Fediverse</strong> through standardized MCP tools, resources, and prompts.
13</p>
14 
15<!-- Trigger CI -->
16 
17<p align="center">
18  <a href="https://badge.fury.io/js/activitypub-mcp"><img src="https://badge.fury.io/js/activitypub-mcp.svg" alt="npm version" /></a>
19  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT" /></a>
20  <a href="https://www.typescriptlang.org/"><img src="https://img.shields.io/badge/TypeScript-007ACC?logo=typescript&logoColor=white" alt="TypeScript" /></a>
21  <a href="https://nodejs.org/"><img src="https://img.shields.io/badge/Node.js-18+-339933?logo=node.js&logoColor=white" alt="Node.js" /></a>
22  <a href="https://modelcontextprotocol.io/"><img src="https://img.shields.io/badge/MCP-Compatible-blueviolet" alt="MCP Compatible" /></a>
23</p>
24 
25<p align="center">
26  <a href="https://github.com/cameronrye/activitypub-mcp/actions"><img src="https://github.com/cameronrye/activitypub-mcp/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
27  <a href="https://www.npmjs.com/package/activitypub-mcp"><img src="https://img.shields.io/npm/dm/activitypub-mcp.svg" alt="npm downloads" /></a>
28  <a href="https://github.com/cameronrye/activitypub-mcp"><img src="https://img.shields.io/github/stars/cameronrye/activitypub-mcp?style=social" alt="GitHub stars" /></a>
29</p>
30 
31---
32 
33<h2 align="center">What's New in v1.1.0</h2>
34 
35<p align="center">
36  <strong>The biggest release yet!</strong> Now with full write capabilities, multi-account support, and enterprise-ready features.
37</p>
38 
39<table align="center">
40  <tr>
41    <td align="center"><strong>Post & Interact</strong><br/>Create posts, reply, boost, favourite, and bookmark directly from your LLM</td>
42    <td align="center"><strong>Multi-Account</strong><br/>Manage multiple fediverse accounts with secure credential storage</td>
43    <td align="center"><strong>Media & Polls</strong><br/>Upload images with alt text, vote on polls, schedule posts</td>
44  </tr>
45  <tr>
46    <td align="center"><strong>Export Anywhere</strong><br/>Export timelines, threads, and accounts to JSON, Markdown, or CSV</td>
47    <td align="center"><strong>HTTP Transport</strong><br/>Production-ready HTTP/SSE mode for enterprise deployments</td>
48    <td align="center"><strong>53 Tools</strong><br/>21 read-only + 28 authenticated + 4 export tools</td>
49  </tr>
50</table>
51 
52<p align="center">
53  <a href="#authenticated-write-tools-v110">See Authenticated Tools</a> |
54  <a href="#content-export-tools-v110">See Export Tools</a> |
55  <a href="CHANGELOG.md">Full Changelog</a>
56</p>
57 
58---
59 
60## Features
61 
62### Core Capabilities
63 
64- **Fediverse Client**: Interact with existing ActivityPub servers (Mastodon, Pleroma, Misskey, etc.)
65- **WebFinger Discovery**: Find and discover actors across the fediverse
66- **MCP Protocol**: Complete MCP server with resources, tools, and prompts
67- **LLM-Optimized**: Designed specifically for LLM interaction patterns
68- **TypeScript**: Fully typed with modern TypeScript and ESM
69- **High Performance**: Efficient resource management and caching
70- **Secure**: Built-in security features and input validation
71- **Dual Transport**: Supports both stdio (Claude Desktop) and HTTP transport modes
72 
73### Fediverse Interaction Features
74 
75- **Remote Actor Discovery**: Find users on any fediverse instance
76- **Timeline Fetching**: Get posts from any user's timeline with pagination support
77- **Trending Content**: Access trending hashtags and posts
78- **Instance Discovery**: Find and explore fediverse instances via live API
79- **Instance Information**: Get detailed info about any server
80- **Search Capabilities**: Search for accounts, hashtags, and posts across instances
81- **Post Threads**: Fetch complete conversation threads with replies
82- **WebFinger Support**: Resolve actor identifiers across the network
83- **Multi-Platform Support**: Works with Mastodon, Pleroma, Misskey, and more
84- **Follower/Following Lists**: Access social connections
85- **Batch Operations**: Fetch multiple actors or posts in a single request
86 
87### MCP Features
88 
89- **Resources** (10 total): Access remote ActivityPub data (actors, timelines, trending, instance info)
90- **Tools** (53 total): Discover, interact, and create content in the fediverse
91  - 21 read-only tools for discovery and exploration (including unified search)
92  - 28 authenticated tools for posting, interactions, polls, media, and scheduling
93  - 4 export tools for data export in JSON, Markdown, or CSV formats
94- **Prompts** (11 total): Templates for fediverse exploration, content strategy, and community analysis
95- **Monitoring**: Built-in logging, audit trails, and performance metrics
96- **Health Checks**: Server health monitoring and diagnostics
97 
98### Authenticated Features (v1.1.0)
99 
100- **Multi-Account Support**: Manage multiple fediverse accounts with secure credential storage
101- **Posting Operations**: Create, reply to, and delete posts
102- **Social Interactions**: Boost, favourite, bookmark, follow, mute, and block
103- **Authenticated Timelines**: Access home timeline, notifications, bookmarks, and favourites
104- **Content Export**: Export timelines, threads, and account data in multiple formats
105 
106### Security & Administration
107 
108- **Instance Blocklist**: Block specific instances by domain or wildcard pattern
109- **Audit Logging**: Comprehensive logging of all tool invocations and resource access
110- **Content Warnings**: Respect and display content warnings from posts
111- **Rate Limiting**: Protect against abuse with configurable rate limits
112 
113## Quick Start
114 
115### Prerequisites
116 
117- **Node.js 18+** (LTS recommended)
118- **npm** or **yarn** package manager
119- **Git** for cloning the repository
120 
121### Cross-Platform Support
122 
123This project works on **Windows**, **macOS**, and **Linux** with automatic platform detection and appropriate script selection.
124 
125### One-Click Installation
126 
127For the fastest setup, use our automated installation script:
128 
129#### Universal (All Platforms)
130```bash
131# Install directly with npx (recommended)
132npx activitypub-mcp install
133 
134# Or clone and run setup
135git clone https://github.com/cameronrye/activitypub-mcp.git
136cd activitypub-mcp
137npm run setup
138```
139 
140#### Platform-Specific Installation
141 
142**Windows (PowerShell):**
143```powershell
144# Clone and setup
145git clone https://github.com/cameronrye/activitypub-mcp.git
146cd activitypub-mcp
147npm run setup:windows
148 
149# Or run PowerShell script directly
150.\scripts\setup.ps1
151```
152 
153**macOS/Linux (Bash):**
154```bash
155# Clone and setup
156git clone https://github.com/cameronrye/activitypub-mcp.git
157cd activitypub-mcp
158npm run setup:unix
159 
160# Or run bash script directly
161bash scripts/setup.sh
162```
163 
164### Manual Installation
165 
1661. **Clone and install dependencies**:
167 
168```bash
169git clone https://github.com/cameronrye/activitypub-mcp.git
170cd activitypub-mcp
171npm install
172```
173 
1742. **Configure environment**:
175 
176**Windows:**
177```cmd
178# Copy environment template
179copy .env.example .env
180 
181# Edit configuration (optional)
182notepad .env
183```
184 
185**macOS/Linux:**
186```bash
187# Copy environment template
188cp .env.example .env
189 
190# Edit configuration (optional)
191nano .env
192```
193 
1943. **Start the MCP server**:
195 
196```bash
197# Start the MCP server (no local ActivityPub server needed)
198npm run mcp
199```
200 
201### Testing the Setup
202 
203**Test MCP server** with MCP Inspector:
204 
205```bash
206# Install MCP Inspector
207npm install -g @modelcontextprotocol/inspector
208 
209# Connect to the MCP server
210mcp-inspector
211```
212 
213### Claude Desktop Integration
214 
215To use this MCP server with Claude Desktop:
216 
2171. **Locate your Claude Desktop config file**:
218   - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
219   - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
220 
2212. **Add the server configuration**:
222 
223```json
224{
225  "mcpServers": {
226    "activitypub": {
227      "command": "npx",
228      "args": ["-y", "activitypub-mcp"]
229    }
230  }
231}
232```
233 
2343. **Restart Claude Desktop** to load the new server.
235 
236## Documentation
237 
238### Quick Reference
239 
240For detailed usage instructions, examples, and troubleshooting, see:
241 
242- **[Usage Guide](docs/guides/USAGE_GUIDE.md)** - Comprehensive usage documentation
243- **[Examples](docs/guides/EXAMPLES.md)** - Practical examples and integration patterns
244- **[API Reference](#api-reference)** - Complete API documentation (below)
245 
246### API Reference
247 
248### MCP Resources
249 
250Resources provide read-only access to fediverse data from any ActivityPub server. All resources return JSON data unless otherwise specified.
251 
252#### Server Info Resource
253 
254Get information about the ActivityPub MCP server:
255 
256```uri
257activitypub://server-info
258```
259 
260**Parameters:**
261- None required
262 
263**Example Response:**
264 
265```json
266{
267  "name": "activitypub-mcp",
268  "version": "1.1.0",
269  "description": "A Model Context Protocol server for exploring and interacting with the existing Fediverse",
270  "capabilities": {
271    "resources": ["server-info", "remote-actor", "remote-timeline", "remote-followers", "remote-following", "instance-info", "trending", "local-timeline", "federated-timeline", "post-thread"],
272    "tools": {
273      "discovery": ["discover-actor", "discover-instances", "discover-instances-live", "recommend-instances"],
274      "content": ["fetch-timeline", "get-post-thread", "search-instance", "search-accounts", "search-hashtags", "search-posts"],
275      "timelines": ["get-trending-hashtags", "get-trending-posts", "get-local-timeline", "get-federated-timeline"],
276      "utility": ["convert-url", "batch-fetch-actors", "batch-fetch-posts"],
277      "system": ["health-check", "performance-metrics"]
278    },
279    "prompts": ["explore-fediverse", "discover-content", "compare-instances", "compare-accounts", "analyze-user-activity", "find-experts", "summarize-trending"]
280  },
281  "features": {
282    "auditLogging": true,
283    "instanceBlocklist": true,
284    "contentWarnings": true,
285    "batchOperations": true
286  }
287}
288```
289 
290#### Remote Actor Resource
291 
292Get information about any actor in the fediverse:
293 
294```uri
295activitypub://remote-actor/{identifier}
296```
297 
298**Parameters:**
299- `identifier` (string): The actor's fediverse handle (e.g., user@mastodon.social)
300 
301**Example Response:**
302 
303```json
304{
305  "@context": ["https://www.w3.org/ns/activitystreams"],
306  "id": "https://mastodon.social/users/alice",
307  "type": "Person",
308  "preferredUsername": "alice",
309  "name": "Alice Smith",
310  "summary": "Software developer passionate about decentralized social networks",
311  "inbox": "https://mastodon.social/users/alice/inbox",
312  "outbox": "https://mastodon.social/users/alice/outbox"
313}
314```
315 
316#### Remote Timeline Resource
317 
318Access any actor's timeline/outbox from across the fediverse:
319 
320```uri
321activitypub://remote-timeline/{identifier}
322```
323 
324**Parameters:**
325- `identifier` (string): The actor's fediverse handle (e.g., user@mastodon.social)
326 
327**Example Response:**
328 
329```json
330{
331  "@context": "https://www.w3.org/ns/activitystreams",
332  "type": "OrderedCollection",
333  "id": "https://mastodon.social/users/alice/outbox",
334  "totalItems": 42,
335  "orderedItems": [...]
336}
337```
338 
339#### Instance Info Resource
340 
341Get information about any fediverse instance:
342 
343```uri
344activitypub://instance-info/{domain}
345```
346 
347**Parameters:**
348- `domain` (string): The instance domain (e.g., mastodon.social)
349 
350**Example Response:**
351 
352```json
353{
354  "domain": "mastodon.social",
355  "software": "mastodon",
356  "version": "4.2.1",
357  "description": "The original server operated by the Mastodon gGmbH non-profit",
358  "registrations": true,
359  "stats": {
360    "user_count": 900000,
361    "status_count": 50000000
362  }
363}
364```
365 
366#### Remote Followers/Following Resources
367 
368Access follower and following lists from any actor:
369 
370```uri
371activitypub://remote-followers/{identifier}
372activitypub://remote-following/{identifier}
373```
374 
375#### Trending Resource (New)
376 
377Get trending hashtags and posts from an instance:
378 
379```uri
380activitypub://trending/{domain}
381```
382 
383#### Local Timeline Resource (New)
384 
385Get the local public timeline from an instance:
386 
387```uri
388activitypub://local-timeline/{domain}
389```
390 
391#### Federated Timeline Resource (New)
392 
393Get the federated public timeline from an instance:
394 
395```uri
396activitypub://federated-timeline/{domain}
397```
398 
399#### Post Thread Resource (New)
400 
401Get a post and its full conversation thread:
402 
403```uri
404activitypub://post-thread/{postUrl}
405```
406 
407### MCP Tools
408 
409Tools enable LLMs to discover and interact with the fediverse. All tools return structured responses with success/error information.
410 
411#### Discover Actor
412 
413Discover and get information about any actor in the fediverse:
414 
415```json
416{
417  "name": "discover-actor",
418  "arguments": {
419    "identifier": "user@mastodon.social"
420  }
421}
422```
423 
424**Parameters:**
425- `identifier` (string, required): Fediverse handle (e.g., user@mastodon.social)
426 
427#### Fetch Timeline
428 
429Fetch posts from any actor's timeline with pagination support:
430 
431```json
432{
433  "name": "fetch-timeline",
434  "arguments": {
435    "identifier": "user@mastodon.social",
436    "limit": 20,
437    "cursor": null,
438    "maxId": null
439  }
440}
441```
442 
443**Parameters:**
444 
445- `identifier` (string, required): Fediverse handle
446- `limit` (number, optional): Number of posts to fetch (1-50, default: 20)
447- `cursor` (string, optional): Pagination cursor from previous response
448- `minId` (string, optional): Return results newer than this ID
449- `maxId` (string, optional): Return results older than this ID
450- `sinceId` (string, optional): Return results since this ID
451 
452#### Get Instance Info
453 
454Get detailed information about any fediverse instance:
455 
456```json
457{
458  "name": "get-instance-info",
459  "arguments": {
460    "domain": "mastodon.social"
461  }
462}
463```
464 
465**Parameters:**
466- `domain` (string, required): Instance domain
467 
468#### Search Instance
469 
470Search for content on a specific fediverse instance:
471 
472```json
473{
474  "name": "search-instance",
475  "arguments": {
476    "domain": "mastodon.social",
477    "query": "typescript",
478    "type": "accounts"
479  }
480}
481```
482 
483**Parameters:**
484- `domain` (string, required): Instance domain to search
485- `query` (string, required): Search query
486- `type` (string, optional): Type of content ("accounts", "statuses", "hashtags")
487 
488#### Discover Instances
489 
490Find popular fediverse instances by category or topic:
491 
492```json
493{
494  "name": "discover-instances",
495  "arguments": {
496    "category": "mastodon",
497    "topic": "technology",
498    "size": "medium"
499  }
500}
501```
502 
503**Parameters:**
504- `category` (string, optional): Software type ("mastodon", "pleroma", "misskey", etc.)
505- `topic` (string, optional): Topic or interest to search for
506- `size` (string, optional): Instance size ("small", "medium", "large")
507- `region` (string, optional): Geographic region or language
508- `beginnerFriendly` (boolean, optional): Show only beginner-friendly instances
509 
510#### Recommend Instances
511 
512Get personalized instance recommendations based on interests:
513 
514```json
515{
516  "name": "recommend-instances",
517  "arguments": {
518    "interests": ["technology", "programming", "open source"]
519  }
520}
521```
522 
523**Parameters:**
524 
525- `interests` (array, required): List of your interests or topics
526 
527#### Discover Instances Live (New)
528 
529Real-time instance discovery via instances.social API:
530 
531```json
532{
533  "name": "discover-instances-live",
534  "arguments": {
535    "software": "mastodon",
536    "language": "en",
537    "minUsers": 1000,
538    "openRegistrations": true,
539    "limit": 20
540  }
541}
542```
543 
544**Parameters:**
545 
546- `software` (enum, optional): Filter by software type (mastodon, pleroma, misskey, pixelfed, lemmy, peertube, any)
547- `language` (string, optional): Filter by language code (e.g., "en", "de", "ja")
548- `minUsers` (number, optional): Minimum number of users
549- `maxUsers` (number, optional): Maximum number of users
550- `openRegistrations` (boolean, optional): Only show instances with open registrations
551- `sortBy` (enum, optional): Sort by "users", "statuses", "connections", or "name"
552- `limit` (number, optional): Number of results (default: 20)
553 
554#### Get Trending Hashtags (New)
555 
556Get currently trending hashtags on an instance:
557 
558```json
559{
560  "name": "get-trending-hashtags",
561  "arguments": {
562    "domain": "mastodon.social",
563    "limit": 20
564  }
565}
566```
567 
568#### Get Trending Posts (New)
569 
570Get currently trending posts on an instance:
571 
572```json
573{
574  "name": "get-trending-posts",
575  "arguments": {
576    "domain": "mastodon.social",
577    "limit": 20
578  }
579}
580```
581 
582#### Get Local Timeline (New)
583 
584Get the local public timeline from an instance:
585 
586```json
587{
588  "name": "get-local-timeline",
589  "arguments": {
590    "domain": "mastodon.social",
591    "limit": 20
592  }
593}
594```
595 
596#### Get Federated Timeline (New)
597 
598Get the federated public timeline from an instance:
599 
600```json
601{
602  "name": "get-federated-timeline",
603  "arguments": {
604    "domain": "mastodon.social",
605    "limit": 20
606  }
607}
608```
609 
610#### Get Post Thread (New)
611 
612Fetch a post and its full conversation thread:
613 
614```json
615{
616  "name": "get-post-thread",
617  "arguments": {
618    "postUrl": "https://mastodon.social/@user/123456789",
619    "depth": 2,
620    "maxReplies": 50
621  }
622}
623```
624 
625#### Search Accounts (New)
626 
627Search for accounts on an instance:
628 
629```json
630{
631  "name": "search-accounts",
632  "arguments": {
633    "domain": "mastodon.social",
634    "query": "developer",
635    "limit": 20
636  }
637}
638```
639 
640#### Search Hashtags (New)
641 
642Search for hashtags on an instance:
643 
644```json
645{
646  "name": "search-hashtags",
647  "arguments": {
648    "domain": "mastodon.social",
649    "query": "programming",
650    "limit": 20
651  }
652}
653```
654 
655#### Search Posts (New)
656 
657Search for posts on an instance:
658 
659```json
660{
661  "name": "search-posts",
662  "arguments": {
663    "domain": "mastodon.social",
664    "query": "typescript",
665    "limit": 20
666  }
667}
668```
669 
670#### Batch Fetch Actors (New)
671 
672Fetch multiple actors in a single request:
673 
674```json
675{
676  "name": "batch-fetch-actors",
677  "arguments": {
678    "identifiers": ["user1@mastodon.social", "user2@fosstodon.org"]
679  }
680}
681```
682 
683#### Batch Fetch Posts (New)
684 
685Fetch multiple posts in a single request:
686 
687```json
688{
689  "name": "batch-fetch-posts",
690  "arguments": {
691    "urls": ["https://mastodon.social/@user/123", "https://fosstodon.org/@user/456"]
692  }
693}
694```
695 
696#### Health Check
697 
698Check the health status of the MCP server:
699 
700```json
701{
702  "name": "health-check",
703  "arguments": {}
704}
705```
706 
707**Parameters:**
708- None required
709 
710#### Performance Metrics
711 
712Get performance metrics for the MCP server:
713 
714```json
715{
716  "name": "performance-metrics",
717  "arguments": {
718    "operation": "discover-actor"
719  }
720}
721```
722 
723**Parameters:**
724- `operation` (string, optional): Specific operation to get metrics for
725 
726### MCP Prompts
727 
728#### Explore Fediverse
729```json
730{
731  "name": "explore-fediverse",
732  "arguments": {
733    "interests": "technology and programming",
734    "instanceType": "mastodon"
735  }
736}
737```
738 
739#### Compare Instances
740```json
741{
742  "name": "compare-instances",
743  "arguments": {
744    "instances": "mastodon.social, fosstodon.org, hachyderm.io",
745    "criteria": "community size and focus"
746  }
747}
748```
749 
750#### Discover Content
751 
752```json
753{
754  "name": "discover-content",
755  "arguments": {
756    "topic": "artificial intelligence",
757    "contentType": "people"
758  }
759}
760```
761 
762#### Compare Accounts (New)
763 
764```json
765{
766  "name": "compare-accounts",
767  "arguments": {
768    "accounts": "user1@mastodon.social, user2@fosstodon.org",
769    "aspects": "posting frequency, topics, engagement"
770  }
771}
772```
773 
774#### Analyze User Activity (New)
775 
776```json
777{
778  "name": "analyze-user-activity",
779  "arguments": {
780    "identifier": "user@mastodon.social",
781    "depth": "standard"
782  }
783}
784```
785 
786#### Find Experts (New)
787 
788```json
789{
790  "name": "find-experts",
791  "arguments": {
792    "topic": "machine learning",
793    "instances": "mastodon.social, fosstodon.org"
794  }
795}
796```
797 
798#### Summarize Trending (New)
799 
800```json
801{
802  "name": "summarize-trending",
803  "arguments": {
804    "instances": "mastodon.social",
805    "focus": "tech"
806  }
807}
808```
809 
810#### Content Strategy (v1.1.0)
811 
812Plan your fediverse content strategy based on trending topics:
813 
814```json
815{
816  "name": "content-strategy",
817  "arguments": {
818    "topics": "programming, open source",
819    "targetAudience": "developers",
820    "postingFrequency": "several-per-week"
821  }
822}
823```
824 
825#### Community Health (v1.1.0)
826 
827Analyze instance moderation and community health:
828 
829```json
830{
831  "name": "community-health",
832  "arguments": {
833    "instance": "fosstodon.org",
834    "concerns": "moderation, spam"
835  }
836}
837```
838 
839#### Migration Helper (v1.1.0)
840 
841Get help planning a migration to a new fediverse instance:
842 
843```json
844{
845  "name": "migration-helper",
846  "arguments": {
847    "currentInstance": "mastodon.social",
848    "targetInstance": "fosstodon.org",
849    "priorities": "moderation, privacy, community focus"
850  }
851}
852```
853 
854#### Thread Composer (v1.1.0)
855 
856Help compose well-structured threaded posts:
857 
858```json
859{
860  "name": "thread-composer",
861  "arguments": {
862    "topic": "Introduction to the Fediverse",
863    "keyPoints": "What is ActivityPub, Popular instances, Getting started",
864    "tone": "informative",
865    "targetLength": "medium"
866  }
867}
868```
869 
870### Authenticated Write Tools (v1.1.0)
871 
872These tools require authentication via environment variables. See [Configuration](#environment-variables) for setup.
873 
874#### Account Management
875 
876- `list-accounts` - List configured accounts
877- `switch-account` - Switch active account
878- `verify-account` - Verify account credentials
879 
880#### Posting Operations
881 
882```json
883{
884  "name": "post-status",
885  "arguments": {
886    "content": "Hello Fediverse!",
887    "visibility": "public",
888    "contentWarning": "optional CW"
889  }
890}
891```
892 
893- `post-status` - Create a new post
894- `reply-to-post` - Reply to an existing post
895- `delete-post` - Delete your own post
896 
897#### Social Interactions
898 
899- `boost-post` / `unboost-post` - Boost (reblog) posts
900- `favourite-post` / `unfavourite-post` - Favourite posts
901- `bookmark-post` / `unbookmark-post` - Bookmark posts
902- `follow-account` / `unfollow-account` - Follow/unfollow accounts
903- `mute-account` / `unmute-account` - Mute accounts
904- `block-account` / `unblock-account` - Block accounts
905 
906#### Authenticated Timelines
907 
908- `get-home-timeline` - Your home timeline
909- `get-notifications` - Your notifications
910- `get-bookmarks` - Your bookmarked posts
911- `get-favourites` - Your favourited posts
912 
913#### Unified Search (NEW)
914 
915Search across accounts, posts, and hashtags in a single query:
916 
917```json
918{
919  "name": "search",
920  "arguments": {
921    "domain": "mastodon.social",
922    "query": "typescript programming",
923    "type": "all",
924    "limit": 20
925  }
926}
927```
928 
929**Parameters:**
930 
931- `domain` (string, required): Instance domain to search
932- `query` (string, required): Search query
933- `type` (string, optional): "all", "accounts", "posts", or "hashtags" (default: "all")
934- `limit` (number, optional): Results per type (1-40, default: 20)
935- `resolve` (boolean, optional): Attempt WebFinger lookup for remote accounts
936 
937#### Relationship Checking (NEW)
938 
939Check your relationship status with other accounts:
940 
941```json
942{
943  "name": "get-relationship",
944  "arguments": {
945    "accountIds": ["12345", "67890"]
946  }
947}
948```
949 
950**Parameters:**
951 
952- `accountIds` (array, required): Account IDs to check relationship status
953 
954**Returns:** Following, followed_by, blocking, muting, and other relationship statuses.
955 
956#### Poll Voting (NEW)
957 
958Vote on polls in posts:
959 
960```json
961{
962  "name": "vote-on-poll",
963  "arguments": {
964    "pollId": "123456",
965    "choices": [0, 2]
966  }
967}
968```
969 
970**Parameters:**
971 
972- `pollId` (string, required): The poll ID to vote on
973- `choices` (array, required): Array of choice indices (0-based)
974 
975**Returns:** Updated poll with current results and visual bar chart.
976 
977#### Media Upload (NEW)
978 
979Upload media files with alt text descriptions:
980 
981```json
982{
983  "name": "upload-media",
984  "arguments": {
985    "filePath": "/path/to/image.jpg",
986    "description": "A beautiful sunset over the ocean",
987    "focus": "0.0,0.5"
988  }
989}
990```
991 
992**Parameters:**
993 
994- `filePath` (string, required): Local file path or URL to upload
995- `description` (string, optional): Alt text for accessibility (recommended)
996- `focus` (string, optional): Focal point as "x,y" (-1.0 to 1.0)
997 
998**Supported types:** Images (jpg, png, gif, webp), Videos (mp4, webm), Audio (mp3, ogg)
999 
1000#### Scheduled Posts (NEW)
1001 
1002Manage scheduled posts:
1003 
1004```json
1005{
1006  "name": "get-scheduled-posts",
1007  "arguments": {
1008    "limit": 20
1009  }
1010}
1011```
1012 
1013```json
1014{
1015  "name": "update-scheduled-post",
1016  "arguments": {
1017    "scheduledPostId": "123",
1018    "scheduledAt": "2026-02-14T18:00:00.000Z"
1019  }
1020}
1021```
1022 
1023```json
1024{
1025  "name": "cancel-scheduled-post",
1026  "arguments": {
1027    "scheduledPostId": "123"
1028  }
1029}
1030```
1031 
1032- `get-scheduled-posts` - List all pending scheduled posts
1033- `update-scheduled-post` - Change the scheduled time
1034- `cancel-scheduled-post` - Cancel a scheduled post
1035 
1036### Content Export Tools (v1.1.0)
1037 
1038Export fediverse content in multiple formats (JSON, Markdown, CSV):
1039 
1040```json
1041{
1042  "name": "export-timeline",
1043  "arguments": {
1044    "identifier": "user@mastodon.social",
1045    "format": "markdown",
1046    "limit": 50
1047  }
1048}
1049```
1050 
1051- `export-timeline` - Export actor timeline
1052- `export-thread` - Export post thread with replies
1053- `export-account-info` - Comprehensive account data export
1054- `export-hashtag` - Export posts with a specific hashtag
1055 
1056## Architecture
1057 
1058### Project Structure
1059 
1060```
1061activitypub-mcp/
1062├── src/                           # Source code
1063│   ├── mcp-main.ts                # MCP server entry point
1064│   ├── mcp-server.ts              # MCP server implementation
1065│   ├── webfinger.ts               # WebFinger discovery client
1066│   ├── remote-client.ts           # Remote ActivityPub client
1067│   ├── instance-discovery.ts      # Static instance discovery
1068│   ├── dynamic-instance-discovery.ts # Live API instance discovery
1069│   ├── instance-blocklist.ts      # Instance blocklist manager
1070│   ├── audit-logger.ts            # Audit logging infrastructure
1071│   ├── health-check.ts            # Health monitoring
1072│   ├── performance-monitor.ts     # Performance tracking
1073│   ├── config.ts                  # Configuration constants
1074│   ├── logging.ts                 # Logging configuration
1075│   ├── auth/                      # Authentication (v1.1.0)
1076│   │   ├── account-manager.ts     # Multi-account management
1077│   │   ├── authenticated-client.ts # Authenticated API client
1078│   │   └── index.ts               # Auth module exports
1079│   ├── mcp/                       # MCP handlers
1080│   │   ├── tools.ts               # Read-only tool implementations
1081│   │   ├── tools-write.ts         # Write operation tools (v1.1.0)
1082│   │   ├── tools-export.ts        # Export tools (v1.1.0)
1083│   │   ├── resources.ts           # Resource implementations
1084│   │   └── prompts.ts             # Prompt implementations
1085│   └── server/                    # Server infrastructure
1086│       ├── http-transport.ts      # HTTP/SSE transport
1087│       ├── adaptive-rate-limiter.ts # Per-instance rate limiting (v1.1.0)
1088│       └── rate-limiter.ts        # Rate limiting
1089├── docs/                          # Documentation
1090├── scripts/                       # Installation & setup scripts
1091├── tests/                         # Test files
1092│   ├── unit/                      # Unit tests
1093│   └── integration/               # Integration tests
1094├── dist/                          # Built JavaScript files
1095├── package.json                   # Dependencies and scripts
1096└── README.md                      # This file
1097```
1098 
1099### Technology Stack
1100- **[WebFinger](https://tools.ietf.org/rfc/rfc7033.txt)**: Actor discovery across the fediverse
1101- **[MCP SDK](https://github.com/modelcontextprotocol/typescript-sdk)**: Model Context Protocol implementation
1102- **[ActivityPub](https://www.w3.org/TR/activitypub/)**: Decentralized social networking protocol
1103- **[LogTape](https://logtape.org/)**: Structured logging
1104- **TypeScript**: Type-safe development
1105 
1106### Communication Flow
1107```
1108LLM Client ←→ MCP Protocol ←→ Fediverse Client ←→ Remote ActivityPub Servers
1109                                     ↓
1110                              WebFinger Discovery
1111                                     ↓
1112                              Remote Data Fetching
1113```
1114 
1115## Documentation
1116 
1117Comprehensive documentation is available in the `docs/` directory:
1118 
1119- **[Setup & Installation](docs/setup/)** - Configuration and installation guides
1120- **[User Guides](docs/guides/)** - Usage examples and tutorials
1121- **[Development](docs/development/)** - Development setup and best practices
1122- **[Specifications](docs/specifications/)** - ActivityPub and protocol specifications
1123 
1124See the [Documentation Index](docs/README.md) for a complete overview.
1125 
1126## Development
1127 
1128### Available Scripts
1129- `npm run mcp` - Start MCP server
1130- `npm run mcp:dev` - Start MCP server in watch mode
1131- `npm run test` - Run tests
1132- `npm run build` - Build TypeScript
1133 
1134### Environment Variables
1135 
1136Create a `.env` file:
1137 
1138```env
1139# MCP Server configuration
1140MCP_SERVER_NAME=activitypub-mcp
1141MCP_SERVER_VERSION=1.1.0
1142 
1143# Transport configuration (stdio or http)
1144MCP_TRANSPORT_MODE=stdio
1145MCP_HTTP_PORT=3000
1146MCP_HTTP_HOST=127.0.0.1
1147MCP_HTTP_CORS_ENABLED=false
1148 
1149# Rate limiting
1150RATE_LIMIT_ENABLED=true
1151RATE_LIMIT_MAX=100
1152RATE_LIMIT_WINDOW=900000
1153 
1154# Logging
1155LOG_LEVEL=info
1156 
1157# Audit logging
1158AUDIT_LOG_ENABLED=true
1159AUDIT_LOG_MAX_ENTRIES=10000
1160 
1161# Instance blocklist (comma-separated domains)
1162BLOCKED_INSTANCES=
1163INSTANCE_BLOCKING_ENABLED=true
1164 
1165# Dynamic instance discovery
1166INSTANCES_SOCIAL_TOKEN=
1167DYNAMIC_INSTANCE_CACHE_TTL=3600000
1168 
1169# Content warnings
1170RESPECT_CONTENT_WARNINGS=true
1171SHOW_CONTENT_WARNINGS=true
1172 
1173# Authentication (for write operations - v1.1.0)
1174ACTIVITYPUB_DEFAULT_INSTANCE=mastodon.social
1175ACTIVITYPUB_DEFAULT_TOKEN=your-oauth-access-token
1176ACTIVITYPUB_DEFAULT_USERNAME=your-username
1177 
1178# Multi-account configuration (JSON format)
1179# ACTIVITYPUB_ACCOUNTS='[{"id":"work","instance":"fosstodon.org","token":"token1","username":"work_account"},{"id":"personal","instance":"mastodon.social","token":"token2","username":"personal_account"}]'
1180```
1181 
1182### HTTP Transport Mode
1183 
1184For production deployments, you can run the server in HTTP mode:
1185 
1186```bash
1187# Start with HTTP transport
1188MCP_TRANSPORT_MODE=http MCP_HTTP_PORT=8080 npm run mcp
1189 
1190# The server exposes:
1191# - /mcp    - MCP protocol endpoint
1192# - /health - Health check endpoint
1193# - /metrics - Performance metrics
1194# - /       - Server info
1195```
1196 
1197### Testing
1198```bash
1199# Test MCP server with inspector
1200mcp-inspector
1201 
1202# Test fediverse interactions
1203npm run test
1204 
1205# Manual testing with specific actors
1206# Use the discover-actor tool to test WebFinger discovery
1207```
1208 
1209## Cross-Platform Compatibility
1210 
1211This project is designed to work seamlessly across different operating systems:
1212 
1213### Supported Platforms
1214- **Windows 10/11** (PowerShell, Command Prompt, Git Bash)
1215- **macOS** (Bash, Zsh)
1216- **Linux** (Bash, most distributions)
1217 
1218### Platform-Specific Features
1219- **Automatic script detection**: npm scripts automatically choose the right script for your platform
1220- **Native path handling**: Proper configuration paths for each platform
1221- **Shell compatibility**: Both PowerShell (.ps1) and Bash (.sh) scripts provided
1222 
1223### Installation Methods by Platform
1224 
1225| Platform | Recommended Method | Alternative Methods |
1226|----------|-------------------|-------------------|
1227| Windows | `npm run setup` | `.\scripts\setup.ps1` or `npm run setup:windows` |
1228| macOS | `npm run setup` | `bash scripts/setup.sh` or `npm run setup:unix` |
1229| Linux | `npm run setup` | `bash scripts/setup.sh` or `npm run setup:unix` |
1230 
1231### Troubleshooting Platform Issues
1232 
1233**Windows PowerShell Execution Policy:**
1234```powershell
1235# If you get execution policy errors, run:
1236Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
1237```
1238 
1239**Windows Git Bash:**
1240```bash
1241# Git Bash users can use Unix-style commands:
1242npm run setup:unix
1243```
1244 
1245**Linux/macOS Permissions:**
1246```bash
1247# If you get permission errors, make scripts executable:
1248chmod +x scripts/*.sh
1249```
1250 
1251## Contributing
1252 
12531. Fork the repository
12542. Create a feature branch: `git checkout -b feature/amazing-feature`
12553. Commit changes: `git commit -m 'Add amazing feature'`
12564. Push to branch: `git push origin feature/amazing-feature`
12575. Open a Pull Request
1258 
1259## License
1260 
1261This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
1262 
1263## Acknowledgments
1264 
1265- [Fedify](https://fedify.dev/) - ActivityPub server framework
1266- [Model Context Protocol](https://modelcontextprotocol.io/) - LLM integration standard
1267- [ActivityPub](https://www.w3.org/TR/activitypub/) - W3C decentralized social networking protocol
1268 
1269## Links
1270 
1271- [ActivityPub Specification](https://www.w3.org/TR/activitypub/)
1272- [Model Context Protocol](https://modelcontextprotocol.io/)
1273- [Fedify Documentation](https://fedify.dev/)
1274- [Fediverse](https://fediverse.info/)
1275 
1276---
1277 
1278Made with ❤️ by [Cameron Rye](https://rye.dev/)
1279