linuxdo

linuxdo is a JSON-first CLI and stdio MCP server for public Linux.do forum endpoints. Use it from a terminal, or expose the same public forum reading tools to AI clients with linuxdo mcp serve.

Features

• Shared CLI and MCP tool catalog from one definition source
• Public topic listing for latest, hot, top, and category views
• Public topic reading through Discourse topic JSON pages
• Public search command with the same JSON-first output contract
• Automatic Cloudflare handling with TLS, Playwright, and real Chrome CDP transports
• linuxdo doctor for runtime checks and optional public endpoint probing

Install

npm install -g linuxdo
# or
pnpm add -g linuxdo

Requires Node.js >=18. Playwright and Chrome are optional and are used only when Cloudflare blocks the primary transport.

Quick Start

linuxdo topics list --filter latest
linuxdo topics list --filter hot
linuxdo topics list --filter top --period weekly
linuxdo topics read --topic-id 2264744 --max-pages 2

Run a public endpoint probe:

linuxdo doctor --verify-public

MCP

Add linuxdo to your MCP client config:

{
  "mcpServers": {
    "linuxdo": {
      "command": "linuxdo",
      "args": ["mcp", "serve"],
      "type": "stdio"
    }
  }
}

CLI Overview

Tool-backed commands default to JSON output and return a non-zero exit code on failure. Use linuxdo <command> --help for command-specific options.

Public Commands

linuxdo topics list --filter latest
linuxdo topics list --filter category --category Development
linuxdo topics read --topic-id 2264744
linuxdo topics search --term "MCP in:title"

Static Commands

linuxdo doctor --verify-public
linuxdo mcp serve

Discovery and Generic Calls

linuxdo tools
linuxdo describe topics search
linuxdo call list_topics filter=latest page=1

• linuxdo tools lists generated command metadata as JSON.
• linuxdo describe ... shows one command or tool schema as JSON.
• linuxdo call ... invokes a tool by MCP tool name with key=value, --json-args, or @payload.json.

MCP Tools

| MCP tool | CLI path | Purpose | | --- | --- | --- | | list_topics | linuxdo topics list | List public topics by filter | | read_topic | linuxdo topics read | Read public topic posts | | search_topics | linuxdo topics search | Search public forum content |

Runtime Notes

Linux.do is protected by Cloudflare. linuxdo handles public endpoint requests with a 3-stage transport chain:

1. TLS transport with a Chrome-like fingerprint
2. Playwright transport when enabled and CDP is disabled
3. Real Chrome CDP transport when enabled

When CDP transport is required, a real Chrome window opens so you can complete the Cloudflare check. The verified browser profile is cached under ~/.cache/linuxdo/chrome-profile by default.

Selected Environment Variables

| Variable | Default | Purpose | | --- | --- | --- | | LINUXDO_PROXY_URL | unset | HTTP proxy for outbound requests | | LINUXDO_CDP_FALLBACK | true | Enable real Chrome CDP transport | | LINUXDO_CDP_PORT | 9222 | Chrome remote debugging port | | LINUXDO_CDP_CHROME_PATH | auto-detect | Override Chrome executable path | | LINUXDO_CDP_USER_DATA_DIR | ~/.cache/linuxdo/chrome-profile | Override the dedicated Chrome profile directory |

Development

pnpm install
pnpm typecheck
pnpm build
pnpm exec vitest run

References

• Pleasurecruise/linux-do-mcp
• Discourse API Documentation
• Linux.do

License

MIT