redlib-mcp

A private, self-hosted window into public Reddit for your AI agent — no login, no tracking, one command, and it works in Claude Code, Codex, Cursor, and Gemini CLI.

redlib-mcp is a Model Context Protocol (MCP) server that lets an AI agent read public Reddit content through a self-hosted Redlib instance that you run and control. It ships three parts that work together:

• an MCP server (the reader — four tools),
• a cross-platform CLI (redlib-mcp setup | restart | update | doctor) that installs and operates the Redlib backend, and
• a setup skill that drives the CLI from your agent.

Redlib itself is never bundled — the CLI clones and builds it from a pinned, reviewed upstream commit on your machine.

Requirements: Docker or Podman, plus Node.js (the MCP server and CLI run via npx; CI-tested on Node 20).

Install

Claude Code — install as a plugin (skill + MCP server in one install):

/plugin marketplace add grazomarin/redlib-mcp
/plugin install redlib-mcp@redlib-mcp

The plugin installs enabled, so the redlib MCP server and the setup-redlib skill are wired immediately. The MCP tools do not work until you build the backend once — enabling the plugin only loads the wiring, not the Redlib instance the tools read from. Run:

redlib-mcp setup            # clones + builds the Redlib container; the `serve` MCP is already wired by the plugin

Until that first build finishes (a multi-minute compile), the redlib MCP shows connected but every tool returns REDLIB_DOWN. Run /reload-plugins (or start a new session) once setup completes.

Other clients (Codex / Cursor / Gemini CLI) — install the skill:

# install the setup skill into your agent
npx skills add grazomarin/redlib-mcp
# then let your agent run it, or run the CLI directly:
npx -y [email protected] setup

setup resolves docker or podman, clones + builds Redlib from source at the pinned reviewed commit, brings it up bound to 127.0.0.1:8080, verifies it end to end, and (with your confirmation) registers the MCP into your client config. The plugin and the CLI both target port 8080 by default; if you run setup --port <n>, set REDLIB_URL in the MCP entry yourself. See redlib-mcp doctor if anything is off.

Updating

Getting a new release of redlib-mcp is separate from the redlib-mcp update CLI command below (which only rebuilds the backend at its pinned commit). New releases do not arrive automatically: a self-hosted, third-party install stays on the version you first installed until you update it.

Claude Code plugin:

/plugin marketplace update redlib-mcp          # fetch the latest release
claude plugin update redlib-mcp@redlib-mcp     # apply it
/reload-plugins                                # activate without a restart

Or enable it once: in /plugin, open the Marketplaces tab, select redlib-mcp, and turn on auto-update, so future releases install at startup.

Other clients (skill install): re-run npx skills add grazomarin/redlib-mcp (or npx skills update) to pull the latest skill, and bump the version in your npx -y redlib-mcp@<version> MCP entry.

If a release moves the pinned Redlib commit, run redlib-mcp update afterward to rebuild the backend at the new pin.

CLI

The redlib-mcp command is usable directly by a human from a terminal and equally drivable by an AI agent — the same commands either way. Run redlib-mcp for the command list, or redlib-mcp <command> --help for a command's flags.

| Command | What it does | | --- | --- | | setup | resolve docker/podman, build Redlib from the pinned commit, run it on 127.0.0.1:8080, verify it, and register the MCP | | restart | restart the backend to refetch a stale Reddit token (reads fail while the container stays up) — finds it on either engine | | update | rebuild at the pinned commit; promote only if it verifies (never tracks upstream HEAD) | | doctor | check engine, daemon, container, health + content, and print how to fix each | | serve | run the MCP server over stdio (your client launches this) |

doctor prints a color-coded checklist with a fix on every failing line, so a person can self-diagnose without an agent:

OK   engine: podman (/usr/bin/podman) — hosts the backend
OK   daemon: reachable
FAIL container on :8080: not running
     -> Run `redlib-mcp setup` to build and start the Redlib backend.

Commands run under docker or podman, chosen automatically (override with --engine docker|podman); restart, doctor, and update locate a running backend on either engine.

Tools

| Tool | What it reads | | --- | --- | | search_reddit | search results (short keyword queries) | | get_subreddit_posts | a subreddit's posts (hot/top/new/rising) + pagination | | get_post | one post with threaded comments | | get_user_activity | a user's recent submissions (source-vetting) |

Usage

Ask your agent a real question in plain language — it searches, reads the relevant threads, and synthesizes what the community actually says. You don't name the tools; it picks them.

• Niche recommendations — "What CLI file manager do people on Reddit recommend, and why?" The agent runs search_reddit, opens the top threads with get_post, and returns the consensus picks (yazi, ranger, nnn, ...) with the trade-offs people cite — the community's answer, not one blog's.
• Compare and weigh opinions — "How do people compare Chakra UI and shadcn/ui, and which do they prefer for what?" It pulls discussions across subreddits and summarizes both camps: the developer-experience arguments, the "own your components" case, the migration gripes.
• Deep-dive one thread — "Summarize the discussion on this post: <reddit-url>" pulls get_post with its threaded comments for the agent to distill.
• Vet a source — "What has u/<name> posted recently?" runs get_user_activity, handy before you trust a hot take.

Everything is read-only and served from your loopback Redlib; the agent never contacts reddit.com directly.

Limitations

• Read-only, public content only. Posts, comments, and user submissions — it cannot post, vote, message, or reach login-gated content.
• Follows upstream Redlib. Reddit periodically changes how its data is served, which can make reads start failing while the container stays up. redlib-mcp restart refetches and usually recovers; redlib-mcp update moves to a newer reviewed Redlib on a release. If it persists at the current pin, it is upstream, not your setup.
• Paced by design. A conservative request cap (REDLIB_MIN_INTERVAL_MS, default 300 ms) spaces requests to your backend.

Configuration

| Variable | Default | Notes | | --- | --- | --- | | REDLIB_URL | http://127.0.0.1:8080 | Your Redlib instance. Use 127.0.0.1, not localhost (a dual-stack host may resolve localhost to ::1 and miss the loopback-only bind). | | REDLIB_MIN_INTERVAL_MS | 300 | Minimum spacing between requests to your backend. | | REDLIB_ALLOW_REMOTE | (unset) | Set to 1 to allow a non-loopback REDLIB_URL (off by default). | | REDLIB_MCP_CLIENT_CONFIG | (unset) | Path to the MCP client config file that setup registers the server into. | | REDLIB_ENGINE | (auto) | Absolute path to a docker/podman binary to force the engine (a bare or relative name is rejected). |

The MCP talks only to your own loopback Redlib and never contacts reddit.com directly; it applies a conservative request rate cap.

HTTP transport (advanced). By default the server speaks MCP over stdio. Set USE_HTTP=true to serve over HTTP on 127.0.0.1 (loopback) at PORT (default 3000); set REDLIB_MCP_TOKEN to require a bearer token (recommended — without it the endpoint is unauthenticated). DNS-rebinding protection is on.

CLI exit codes (setup/restart/update/doctor): 0 success · 2 bad flag/unknown command · 3 container engine/daemon unreachable · 4 container started but unhealthy · 5 verification failed (build discarded) · 6 verification inconclusive (kept current image).

Platform support

| OS | Status | | --- | --- | | Linux | Tested (reference platform) | | macOS | Experimental until verified | | Windows | Experimental until verified — help wanted |

The code targets all three (Node + Docker Desktop / Podman); the labels reflect test coverage, not intent.

Support

redlib-mcp is free and open source. If it saves you time, you can support its upkeep:

Your responsibility

You run and control the Redlib backend on your own machine. You are responsible for your use of it and for complying with the terms of the services you access. This project does not host any instance and ships no credentials.

License and attribution

• This wrapper is MIT (see LICENSE), derived from devthatdoes/redlib-mcp-server.
• Redlib is a separate program under AGPL-3.0, cloned and built on your machine — see NOTICE.
• Not affiliated with or endorsed by Reddit, Inc. "Reddit" is used only to describe the public content this tool reads.