Redlib MCP Server

Un servidor MCP que integra tu instancia privada de Redlib, permitiendo que asistentes de IA accedan para utilizar Redlib.

GitHub

Documentación

Redlib MCP Server

Docker Pulls Docker Image Size

A Model Context Protocol (MCP) server that enables AI agents to interact with Reddit through your private Redlib instance. No Reddit API keys required - just a running Redlib instance!

https://github.com/user-attachments/assets/66eec084-e911-4eed-a51f-be303e86f1a7

Table of Contents

Features

  • Privacy-First - Uses your self-hosted Redlib, no tracking or API keys
  • 3 Powerful Tools - Search posts, get hot posts, fetch full post details with comments
  • Docker Ready - Both simple and hardened Docker images available
  • Easy Setup - Works with Claude Desktop, Cursor, VS Code, Codex, ForgeCode, KiloCode and any MCP-compatible client
  • Structured Output - Returns clean JSON instead of raw HTML

Current Implementation: Stdio Transport

Important: This server currently uses stdio transport (stdin/stdout communication) for local development. It runs as a child process and communicates through standard input/output.

What This Means:

  • No HTTP endpoint - The server does not expose any HTTP ports
  • Local-only - Designed for local development and testing scenarios
  • Child process - MCP clients spawn this server as a subprocess
  • No network access - All communication happens locally via stdin/stdout

Future Plans:

HTTP transport functionality is planned for future releases to enable:

  • Remote access over HTTP
  • Multiple concurrent client connections
  • Production deployment scenarios
  • Network-based health checks

Prerequisites

Before using this MCP server, you need:

  1. Redlib Instance - A running Redlib instance (default: http://localhost:8080)

  2. MCP Client - One of:

Quick Start

Option 1: Docker (Recommended)

# Pull and run the default version
docker run -i --rm \
  --network host \
  -e REDLIB_URL=http://localhost:8080 \
  alfafadock/mcp-redlib:latest

Option 2: Hardened Docker (Security-Focused)

# Uses non-root user and minimal privileges
docker run -i --rm \
  --network host \
  --cap-drop=ALL \
  --security-opt no-new-privileges:true \
  -e REDLIB_URL=http://localhost:8080 \
  alfafadock/mcp-redlib:hardened

Option 3: Local Development

# Clone and setup
git clone https://github.com/Devthatdoes/redlib-mcp-server.git
cd redlib-mcp-server

# Install dependencies
npm install

# Build
npm run build

# Run
npm start

Docker Compose

Click to expand Docker Compose setup

Create docker-compose.yml:

services:
  redlib-mcp:
    image: alfafadock/mcp-redlib:latest
    container_name: redlib-mcp
    network_mode: "host"  # Uses host network for MCP client communication
    environment:
      - REDLIB_URL=http://localhost:8080  # Change if Redlib is on a different port
    restart: unless-stopped
    # For hardened image, change image to: alfafadock/mcp-redlib:hardened

Configuration

Environment Variables

VariableDefaultDescription
REDLIB_URLhttp://localhost:8080URL of your Redlib instance

Custom Redlib Port Example

If your Redlib runs on a different port (e.g., 8085):

docker run -i --rm \
  --network host \
  -e REDLIB_URL=http://localhost:8085 \
  alfafadock/mcp-redlib:latest

Example .env File

Copy .env.example to .env and modify as needed:

cp .env.example .env

Available Tools

1. search_reddit

Search Reddit posts using your private Redlib instance.

Parameters:

  • query (required) - Search query string
  • subreddit (optional) - Limit search to specific subreddit

Example:

{
  "query": "rust programming",
  "subreddit": "rust"
}

Returns: JSON with post IDs, titles, authors, scores, and comment counts.

2. get_subreddit_hot

Get hot posts from a specific subreddit.

Parameters:

  • subreddit (required) - Subreddit name (without r/)
  • limit (optional) - Number of posts (default: 25)

Example:

{
  "subreddit": "rust",
  "limit": 10
}

3. get_post

Get a specific post with its comments.

Parameters:

  • subreddit (required) - Subreddit name
  • postId (required) - Reddit post ID (from search results)

Example:

{
  "subreddit": "rust",
  "postId": "abc123"
}

Returns: Full post body, score, and up to 10 top comments.

🔌 Integration with AI Clients

Claude Desktop

Edit ~/.config/claude/claude_desktop_config.json (Linux/macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "redlib": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "--network", "host",
        "-e", "REDLIB_URL=http://localhost:8080",
        "alfafadock/mcp-redlib:latest"
      ]
    }
  }
}

For custom Redlib port (e.g., 8085):

{
  "mcpServers": {
    "redlib": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "--network", "host",
        "-e", "REDLIB_URL=http://localhost:8085",
        "alfafadock/mcp-redlib:latest"
      ]
    }
  }
}

After updating: Restart Claude Desktop. You should see a hammer icon (🔨) indicating MCP tools are available.

Reference: Claude Desktop MCP Docs

Cursor

Add to ~/.cursor/mcp.json (global) or .cursor/mcp.json (project level):

{
  "mcpServers": {
    "redlib": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "--network", "host", "-e", "REDLIB_URL=http://localhost:8080", "alfafadock/mcp-redlib:latest"]
    }
  }
}

Project-level setup: Create .cursor/mcp.json in your project root.

After updating: Cursor will automatically detect the changes. Use the Command Palette (Cmd/Ctrl+Shift+P) and search for "MCP" to manage servers.

Reference: Cursor MCP Documentation

VS Code / GitHub Copilot

Option A: Workspace Configuration

Create .vscode/mcp.json in your project:

{
  "servers": {
    "redlib": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "--network", "host", "-e", "REDLIB_URL=http://localhost:8080", "alfafadock/mcp-redlib:latest"]
    }
  }
}

Option B: User Configuration (Global)

Use Command Palette (Cmd/Ctrl+Shift+P) → "MCP: Open User Configuration":

{
  "mcp": {
    "servers": {
      "redlib": {
        "command": "docker",
        "args": ["run", "-i", "--rm", "--network", "host", "-e", "REDLIB_URL=http://localhost:8080", "alfafadock/mcp-redlib:latest"]
      }
    }
  }
}

After updating: Reload VS Code. The tools will appear in GitHub Copilot's Agent Mode.

Reference: VS Code MCP Documentation

OpenAI Codex

Edit ~/.codex/config.toml (global) or .codex/config.toml (project):

[mcp_servers.redlib]
command = "docker"
args = ["run", "-i", "--rm", "--network", "host", "-e", "REDLIB_URL=http://localhost:8080", "alfafadock/mcp-redlib:latest"]

Project-level setup: Create .codex/config.toml in your project root.

After updating: Restart Codex. Use codex mcp list to verify the server is loaded.

Reference: Codex MCP Documentation

ForgeCode

ForgeCode supports MCP servers via the forge mcp command for easy import.

Option A: Quick Import (Recommended)

Use the built-in MCP import functionality:

# Import the Redlib MCP server
forge mcp import alfafadock/mcp-redlib:latest

# List imported servers
forge mcp list

# Reload to apply changes
forge mcp reload

Option B: Project Configuration

Create .mcp.json in your project root:

{
  "mcpServers": {
    "redlib": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "--network", "host", "-e", "REDLIB_URL=http://localhost:8080", "alfafadock/mcp-redlib:latest"]
    }
  }
}

Option C: Global Configuration

Edit ForgeCode's config directory (check extension settings for the exact path).

After updating: Reload the ForgeCode extension using forge mcp reload. The MCP tools should appear in the AI assistant interface.

Reference: ForgeCode Documentation

KiloCode

Option A: Global Configuration

Edit ~/.config/kilo/kilo.jsonc or use Settings → MCP in KiloCode:

{
  "mcpServers": {
    "redlib": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "--network", "host", "-e", "REDLIB_URL=http://localhost:8080", "alfafadock/mcp-redlib:latest"]
    }
  }
}

Option B: Project Configuration

Create .kilocode/mcp.json or kilo.jsonc in your project root:

{
  "mcpServers": {
    "redlib": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "--network", "host", "-e", "REDLIB_URL=http://localhost:8080", "alfafadock/mcp-redlib:latest"]
    }
  }
}

After updating: Open KiloCode Settings → MCP → Add Server, or edit the config file directly.

Reference: KiloCode MCP Documentation

Security: Default vs Hardened

FeatureDefault (latest)Hardened (hardened)
UserrootNon-root (mcpuser)
File Ownershiprootmcpuser
Build StagesSingleMulti-stage (smaller)
Runtime CapsDefaultRequires --cap-drop=ALL
Use CaseDevelopment, testingProduction

Using Hardened Image

docker run -i --rm \
  --cap-drop=ALL \
  --security-opt no-new-privileges:true \
  --network host \
  -e REDLIB_URL=http://localhost:8080 \
  alfafadock/mcp-redlib:hardened

Development

Project Structure

redlib-mcp-server/
├── src/
│   └── index.ts          # Main server code (stdio transport)
├── dist/                  # Compiled JavaScript (gitignored)
├── Dockerfile             # Default Docker image
├── Dockerfile.hardened    # Hardened Docker image
├── docker-compose.yml     # Production compose
├── package.json
├── tsconfig.json
└── README.md

Build from Source

# Install dependencies
npm install

# Build TypeScript
npm run build

# Run locally
npm start

Build Custom Docker Images

# Default version
docker build -t redlib-mcp-server .

# Hardened version
docker build -f Dockerfile.hardened -t redlib-mcp-server:hardened .

Example Usage with AI

Once connected to your AI client (e.g., Claude), you can:

User: "Search Reddit for 'home lab setup' and summarize the top results"

AI uses search_reddit tool →
Returns structured JSON with posts →
AI summarizes the findings for you

User: "Get the full post and comments for that Rust tutorial I searched earlier"

AI uses get_post with postId →
Returns post body + comments →
AI provides detailed analysis

Contributing

Contributions welcome! Please:

  1. Fork the repository
  2. Create a feature branch
  3. Submit a pull request

License

MIT License - feel free to use this project however you want!

Acknowledgments

  • Redlib - The private Reddit front-end this server interfaces with
  • Model Context Protocol - The protocol that makes this integration possible
  • Cheerio - HTML parsing library used to extract structured data

Links

Made with ❤️ for the privacy-conscious Reddit community