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.