Configuration Guide

Comprehensive guide to configuring the ActivityPub MCP Server for your specific needs. Learn about environment variables, client integration, and advanced configuration options.

Configuration Overview

The ActivityPub MCP Server can be configured through:

Environment Variables - Runtime configuration
Client Configuration - MCP client settings (Claude Desktop, etc.)
Command Line Arguments - Override settings at startup

Environment Variables

Core Settings

Variable	Default	Description	Example
`LOG_LEVEL`	`info`	Logging verbosity level	`debug`, `info`, `warn`, `error`
`USER_AGENT`	`ActivityPub-MCP-Server/1.0`	HTTP User-Agent header	`MyBot/1.0 (+https://example.com)`
`REQUEST_TIMEOUT`	`30000`	HTTP request timeout (ms)	`60000`
`MAX_RETRIES`	`3`	Maximum retry attempts	`5`

Cache Settings

Variable	Default	Description	Example
`CACHE_TTL`	`300`	Default cache TTL (seconds)	`600`
`ACTOR_CACHE_TTL`	`300`	Actor info cache TTL	`900`
`INSTANCE_CACHE_TTL`	`3600`	Instance info cache TTL	`7200`
`TIMELINE_CACHE_TTL`	`120`	Timeline cache TTL	`300`

Rate Limiting

Variable	Default	Description	Example
`RATE_LIMIT_REQUESTS`	`100`	Requests per window	`200`
`RATE_LIMIT_WINDOW`	`900`	Rate limit window (seconds)	`1800`
`CONCURRENT_REQUESTS`	`10`	Max concurrent requests	`20`

Client Configuration

Claude Desktop Configuration

Add the server to your Claude Desktop configuration file:

Basic Configuration

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

Advanced Configuration

{
  "mcpServers": {
    "activitypub": {
      "command": "npx",
      "args": ["-y", "activitypub-mcp"],
      "env": {
        "LOG_LEVEL": "debug",
        "USER_AGENT": "MyCustomBot/1.0",
        "REQUEST_TIMEOUT": "60000",
        "CACHE_TTL": "600",
        "RATE_LIMIT_REQUESTS": "50"
      }
    }
  }
}

Configuration File Locations

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

Other MCP Clients

For other MCP-compatible clients, use similar configuration patterns:

Generic MCP Client

{
  "servers": {
    "activitypub": {
      "command": "npx",
      "args": ["activitypub-mcp"],
      "environment": {
        "LOG_LEVEL": "info"
      }
    }
  }
}

⚙️ Advanced Configuration

Development Mode

For development and debugging:

export DEBUG=activitypub-mcp:*
export LOG_LEVEL=debug
export REQUEST_TIMEOUT=120000
npm run dev

Production Optimization

Recommended settings for production use:

export LOG_LEVEL=warn
export CACHE_TTL=900
export RATE_LIMIT_REQUESTS=200
export CONCURRENT_REQUESTS=20

Proxy Configuration

If you need to use a proxy:

export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080
export NO_PROXY=localhost,127.0.0.1

Configuration Validation

Checking Your Configuration

Validate your configuration before starting:

# Check configuration syntax
npm run config:validate

# Test server startup
npm run test:config

# View current configuration
npm run config:show

Common Configuration Issues

Invalid JSON: Check for syntax errors in client config files
Missing quotes: Environment variable values should be strings
Wrong paths: Verify command paths and file locations
Permission issues: Ensure the server has necessary permissions

Next Steps

Cross-Platform Setup

Platform-specific installation and configuration instructions.

Basic Usage Guide

Learn how to use the server once it's configured.

Troubleshooting

Solutions for common configuration problems.