Installation & Setup

Prerequisites

Node.js 20+

Requires Node.js 20 LTS or later (Node 18 reached end-of-life April 30, 2025).

Download Node.js

Claude Desktop (Optional)

For the best experience, install Claude Desktop for seamless AI integration.

Download Claude

MCP Inspector (Optional)

Useful for testing and debugging MCP connections.

npm install -g @modelcontextprotocol/inspector

Quick Installation

The fastest way to get started is using npx:

Run the Server

npx -y activitypub-mcp

This command will:

  • Download and run the latest version of the server over stdio

There is no auto-install step — the server does not detect or configure your MCP client for you. Instead, add the server to your MCP client’s configuration (see below) and restart the client. The client launches the server for you on demand.

Manual Configuration

Add this to your Claude Desktop configuration, then restart Claude Desktop:

{
  "mcpServers": {
    "activitypub": {
      "command": "npx",
      "args": ["-y", "activitypub-mcp"],
      "env": {
        "LOG_LEVEL": "info"
      }
    }
  }
}

To sign in to a fediverse account for authenticated tools, see Authentication.

Configuration Options

Customize the server behavior with environment variables:

VariableDefaultDescription
LOG_LEVELinfoLogging level: debug, info, warning, error, fatal
USER_AGENTActivityPub-MCP-Client/<version>Custom User-Agent for HTTP requests
REQUEST_TIMEOUT10000HTTP request timeout in milliseconds (10 seconds)
CACHE_TTL300000Cache time-to-live in milliseconds (5 minutes)
MCP_HTTP_SECRETnoneRequired when MCP_TRANSPORT_MODE=http. At least 16 chars (32+ recommended); gates /mcp via Bearer auth. /health stays unauthenticated.
MCP_HTTP_ALLOWED_ORIGINSemptyComma-separated Origin allowlist for DNS-rebinding protection. Empty → derived from the CORS origins.
MCP_HTTP_ALLOWED_HOSTSemptyComma-separated allowed Host header values for DNS-rebinding protection.
ACTIVITYPUB_ENABLE_WRITESfalseSet to true to register write tools. Read-only by default.
MCP_THREAD_MAX_DEPTH5Max recursion depth for get-post-thread.
MCP_THREAD_MAX_REPLIES50Max total replies fetched per thread.
MCP_THREAD_CROSS_ORIGIN_FETCHfalseSet true to fetch replies whose origin differs from the root post.
ACTIVITYPUB_ACCOUNTSnoneMulti-account config. Uses the pipe (|) delimiter: id|instance|token|username|label. The legacy colon-delimited form is rejected at startup.

HTTP transport notes for v3:

  • MCP_HTTP_SECRET is required. Requests to /mcp must include Authorization: Bearer <secret>. /health stays unauthenticated for load balancers.
  • The /metrics endpoint was removed in v3. Only /mcp and /health are available.
  • MCP_HTTP_CORS_ORIGINS and MCP_HTTP_ALLOWED_ORIGINS are distinct, independently-read variables. MCP_HTTP_CORS_ORIGINS (with MCP_HTTP_CORS_ENABLED) controls CORS for browser clients; MCP_HTTP_ALLOWED_ORIGINS is the DNS-rebinding Origin allowlist (empty → derived from the CORS origins). Both default to empty.

Verification

Verify your installation is working correctly:

Step 1: Test MCP Connection

Use the MCP Inspector to test the connection:

npx @modelcontextprotocol/inspector

Connect to: npx activitypub-mcp

Step 2: Test Basic Functionality

Try discovering a fediverse actor:

# In MCP Inspector or Claude Desktop
discover-actor @mastodon@mastodon.social

Step 3: Check Server Info

Verify the server is providing information:

# Request the server-info resource
activitypub://server-info

Advanced Setup

Development Setup

For development or local testing:

git clone https://github.com/cameronrye/activitypub-mcp.git
cd activitypub-mcp
npm install
npm run build
npm run mcp

Docker Setup

Run the server in a container:

docker run --rm -i \
  -e LOG_LEVEL=debug \
  activitypub-mcp

Custom Installation Path

Install to a specific location:

npm install -g activitypub-mcp
activitypub-mcp

Next Steps