Alignment Forum Server

An MCP (Model Context Protocol) server that provides access to alignment-related posts from LessWrong and Alignment Forum. This server acts as a research mentor, helping you quickly understand AI alignment concepts and discover unknown unknowns through semantic search and content retrieval.

Features

• Semantic Search: Search through 60+ alignment posts using natural language queries
• Recent Posts: Browse the latest alignment research chronologically
• Full Article Access: Retrieve complete article content including HTML, metadata, and images
• Daily Updates: Automatically syncs with LessWrong via GitHub Actions
• Efficient Storage: CSV-based approach with plaintext descriptions
• High-Quality Content: Includes major works by Eliezer Yudkowsky, Paul Christiano, Nate Soares, and others

Quick Start (Recommended)

The easiest way to use this MCP server is with the hosted deployment. Just add this to your Claude Desktop config:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Linux: ~/.config/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "alignment-forum": {
      "url": "https://alignmentforum.fastmcp.app/mcp",
      "transport": "sse"
    }
  }
}

Then completely quit and restart Claude Desktop. That's it! You can now search and read Alignment Forum posts directly in Claude.

Local Installation (Optional)

Prerequisites

• Python 3.10 or higher
• pip or uv package manager

Setup

1. Clone the repository:

   cd ~/Github
   git clone https://github.com/YOUR_USERNAME/mcp-alignmentforum.git
   cd mcp-alignmentforum
   

2. Install dependencies:

   pip install -e .
   

   Or using uv (recommended):

   uv pip install -e .
   

3. Update configuration:

   • Edit src/mcp_alignmentforum/server.py
   • Replace YOUR_USERNAME with your GitHub username in the CSV_URL constant

4. Run initial data collection (optional):

   export OPENROUTER_API_KEY="your-api-key-here"
   python scripts/update_posts.py
   

Testing the Server

Before configuring Claude Desktop, you can test the MCP server using the MCP Inspector:

# Test remote server (recommended)
npx @modelcontextprotocol/inspector sse \
  https://alignmentforum.fastmcp.app/mcp

# Test local server
npx @modelcontextprotocol/inspector \
  /usr/local/bin/uv \
  --directory /Users/ram/Github/mcp-alignmentforum \
  run \
  mcp-alignmentforum

This will:

1. Start the MCP server
2. Open a web interface at http://localhost:5173
3. Allow you to interactively test all three tools:
   • search_posts - Semantic search through alignment posts
   • list_recent_posts - Browse recent posts chronologically
   • fetch_article_content - Get full article content

Usage with Claude Desktop

Remote Server (Recommended)

See the Quick Start section above to use the hosted deployment at https://alignmentforum.fastmcp.app/mcp.

Local Server (Advanced)

If you've installed the server locally, add the following to your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Linux: ~/.config/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "alignment-forum": {
      "command": "/usr/local/bin/uv",
      "args": [
        "--directory",
        "/Users/ram/Github/mcp-alignmentforum",
        "run",
        "mcp-alignmentforum"
      ]
    }
  }
}

Note: Replace /Users/ram/Github/mcp-alignmentforum with the actual path to your cloned repository.

Restart Claude Desktop

After updating the configuration, completely quit and restart Claude Desktop for the changes to take effect.

Remote Deployment (Railway)

Note: A public deployment is already available at https://alignmentforum.fastmcp.app/mcp (see Quick Start). The instructions below are for deploying your own custom instance.

Deploy to Railway

Deploy on Railway

Or manually deploy:

1. Push your code to GitHub (if not already done)

2. Create a new project on Railway:

   • Go to railway.app
   • Click "New Project"
   • Select "Deploy from GitHub repo"
   • Choose mcp-alignmentforum

3. Railway will automatically:

   • Detect the Dockerfile
   • Install dependencies from pyproject.toml
   • Start the server using the Procfile
   • Assign a public URL (e.g., https://your-app.railway.app)

4. Get your deployment URL:

   • Go to your Railway project settings
   • Copy the public domain URL
   • Your SSE endpoint will be: https://your-app.railway.app/mcp

Use Custom Remote Deployment in Claude Desktop

Update your Claude Desktop config to use your custom deployment:

{
  "mcpServers": {
    "alignment-forum-custom": {
      "url": "https://your-app.railway.app/mcp",
      "transport": "sse"
    }
  }
}

Replace your-app.railway.app with your actual Railway deployment URL.

Environment Variables (Optional)

Railway deployment doesn't require any environment variables, but you can add:

• PORT - Railway sets this automatically (default: 8000)
• HOST - Defaults to 0.0.0.0

Monitoring

• Railway Dashboard: Monitor logs, metrics, and deployments
• Health Check: Railway automatically checks / endpoint
• Auto-deploy: Pushes to GitHub automatically trigger redeployments

Available MCP Tools

1. search_posts

Search through Alignment Forum posts using natural language queries with semantic search.

Parameters:

• query (string, required): Natural language search query (e.g., "mesa-optimization risks")
• limit (integer, optional): Maximum results to return (default: 20, max: 100)
• offset (integer, optional): Results to skip for pagination (default: 0)

Returns: JSON object with matching posts and similarity scores

Example usage in Claude:

Search for posts about mesa-optimizers and inner alignment
Find articles discussing deceptive alignment

2. list_recent_posts

List recent Alignment Forum posts in chronological order (newest first).

Parameters:

• limit (integer, optional): Maximum results to return (default: 20, max: 100)
• offset (integer, optional): Results to skip for pagination (default: 0)

Returns: JSON object with posts array and pagination info

Example usage in Claude:

Show me the 10 most recent alignment forum posts
What are the latest posts on the alignment forum?

3. fetch_article_content

Fetch the full content of a specific Alignment Forum article.

Parameters:

• post_id (string, required): The post ID (_id field) or slug from the database
• url (string, optional): Direct URL to the post (used as fallback)

Returns: Complete article with HTML content, metadata, and statistics

Example usage in Claude:

Fetch the full article content for post ID abc123xyz456789ab
Get the complete text of the article with slug "risks-from-learned-optimization"

Daily Updates

GitHub Actions Workflow

The repository includes a GitHub Actions workflow that automatically updates the CSV file daily:

• Schedule: 3:47 AM UTC every day
• Manual trigger: Can be run manually from the Actions tab

Setup for Automated Updates

1. Go to your GitHub repository settings → Secrets and variables → Actions

2. Add a new secret:

   • Name: OPENROUTER_API_KEY
   • Value: Your OpenRouter API key from https://openrouter.ai/

3. Enable GitHub Actions:

   • Go to the "Actions" tab
   • Enable workflows if prompted

The workflow will:

1. Fetch all posts from Alignment Forum
2. Generate summaries using OpenRouter (or use fallback descriptions)
3. Write to data/alignment-forum-posts.csv
4. Commit and push changes

Development

Project Structure

mcp-alignmentforum/
├── README.md                          # This file
├── pyproject.toml                     # Python project configuration
├── .gitignore                         # Git ignore rules
├── src/
│   └── mcp_alignmentforum/
│       ├── __init__.py               # Package initialization
│       └── server.py                 # MCP server with 3 tools
├── scripts/
│   └── update_posts.py               # Daily update script
├── data/
│   ├── .gitkeep                      # Track directory in git
│   └── alignment-forum-posts.csv     # Generated by GitHub Actions
└── .github/
    └── workflows/
        └── update-posts.yml          # Daily GitHub Actions workflow

Running Locally

Start the MCP server:

python src/mcp_alignmentforum/server.py

The server will run on stdio and wait for MCP protocol messages.

Run the update script:

# Without OpenRouter (uses plaintext descriptions)
python scripts/update_posts.py

# With OpenRouter (generates AI summaries)
export OPENROUTER_API_KEY="your-key"
python scripts/update_posts.py

Testing

You can test the GraphQL queries directly at: https://www.alignmentforum.org/graphiql

Code Quality

# Install dev dependencies
pip install -e ".[dev]"

# Format code
black src/ scripts/

# Lint code
ruff check src/ scripts/

# Type check
mypy src/

API Details

Alignment Forum GraphQL API

• Endpoint: https://www.alignmentforum.org/graphql
• GraphiQL Explorer: https://www.alignmentforum.org/graphiql
• Rate Limits: Be respectful, add delays between requests
• Documentation: Based on LessWrong codebase

OpenRouter API

• Endpoint: https://openrouter.ai/api/v1/chat/completions
• Model Used: openai/gpt-3.5-turbo (reliable and cost-effective)
• Purpose: Generate 2-3 sentence summaries of posts
• Fallback: Uses plaintextDescription if API fails or key not provided

Troubleshooting

MCP server not appearing in Claude Desktop

1. Check that the path in claude_desktop_config.json is correct
2. Ensure Python 3.10+ is installed: python3 --version
3. Verify dependencies are installed: pip list | grep mcp
4. Check Claude Desktop logs:
   • macOS: ~/Library/Logs/Claude/
   • Look for error messages related to mcp-alignmentforum

CSV file not found (404 error)

1. Make sure you've updated the CSV_URL in server.py with your GitHub username
2. Verify the CSV file exists at: https://raw.githubusercontent.com/YOUR_USERNAME/mcp-alignmentforum/main/data/alignment-forum-posts.csv
3. Run the update script to generate the initial CSV: python scripts/update_posts.py
4. Commit and push the CSV file to GitHub

GitHub Actions not running

1. Go to repository Settings → Actions → General
2. Ensure "Allow all actions and reusable workflows" is selected
3. Check that the workflow file is in .github/workflows/
4. Manually trigger from Actions tab to test

Import errors when running server

# Reinstall dependencies
pip install --upgrade mcp httpx 'gql[httpx]' pydantic

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Acknowledgments

• Alignment Forum for providing the content and API
• Model Context Protocol for the MCP specification
• Anthropic for Claude and Claude Desktop

Support

For issues, questions, or suggestions, please open an issue on GitHub.