linuxdo

Linux.do CLI and MCP server. Browse topics, search posts, read notifications, and more -- all from your AI coding assistant or terminal.

Features

• 6 MCP tools: list topics, read threads, search, notifications, bookmarks, private messages
• 3-layer Cloudflare bypass: TLS fingerprinting → Playwright → real Chrome CDP fallback
• Interactive auth: guided API key generation via Discourse User API protocol
• Diagnostics: linuxdo doctor validates runtime and API connectivity

Install

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

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

Quick Start

1. Get your API key

linuxdo auth

This opens a browser for Linux.do authorization and outputs your API key and username.

2. Configure MCP

Add to your MCP client config (e.g. .mcp.json for Claude Code):

{
  "mcpServers": {
    "linuxdo": {
      "command": "linuxdo-mcp",
      "env": {
        "LINUXDO_USER_API_KEY": "your-api-key",
        "LINUXDO_USERNAME": "your-username"
      },
      "type": "stdio"
    }
  }
}

3. Verify (optional)

linuxdo doctor --verify-api

MCP Tools

| Tool | Description | | ------------------- | ----------------------------------------------------------- | | list_topics | List topics by filter: latest, hot, top, new, unread, category, etc. | | read_topic | Read a topic's content with replies (supports pagination) | | search_topics | Search with Discourse syntax (in:title, category:, @user, etc.) | | get_notifications | Get recent notifications, filterable by type | | get_bookmarks | Get your bookmarked posts | | get_messages | Get your private messages |

Cloudflare Bypass

Linux.do uses Cloudflare protection. The server handles this automatically with a 3-layer strategy:

Request
  |
  v
TLS Transport (primary)          -- TLS fingerprint mimics Chrome
  |  blocked?
  v
Playwright Transport (fallback)  -- headless Chromium with anti-detection
  |  blocked?
  v
CDP Transport (last resort)      -- real Chrome, manual CF verification

CDP fallback: When Cloudflare Turnstile blocks automated browsers, a real Chrome window opens for you to complete verification manually. After that, the session is reused for all subsequent requests. The Chrome profile is persisted at ~/.cache/linuxdo-mcp/chrome-profile so future sessions often pass automatically.

CLI Commands

linuxdo mcp serve

Start the MCP server on stdio. Alias: linuxdo-mcp.

linuxdo auth

Interactive API key generation flow.

Options:

• --app-name <name> -- application name (default: linuxdo)
• --client-id <id> -- custom client ID
• --scopes <list> -- comma-separated scopes
• --no-open -- don't auto-open browser
• --no-verify -- skip key verification

linuxdo doctor

Validate environment and runtime.

Options:

• --verify-api -- perform a real API probe

Environment Variables

Required

| Variable | Description | | ---------------------- | ---------------------- | | LINUXDO_USER_API_KEY | Discourse User API Key | | LINUXDO_USERNAME | linux.do username |

Optional

| Variable | Default | Description | | ---------------------------------------- | --------- | ------------------------------- | | LINUXDO_PROXY_URL | | HTTP proxy URL | | LINUXDO_TIMEOUT_SECONDS | 30 | TLS request timeout | | LINUXDO_MAX_RETRIES | 3 | Rate-limit retry count | | LINUXDO_CDP_FALLBACK | true | Enable CDP real Chrome fallback | | LINUXDO_CDP_PORT | 9222 | Chrome remote debugging port | | LINUXDO_CDP_NAVIGATION_TIMEOUT_MS | 120000 | CDP CF verification timeout (ms)| | LINUXDO_CDP_CHROME_PATH | auto-detect| Chrome executable path override |

| Variable | Default | Description | | ---------------------------------------- | -------------------------------- | -------------------------------------- | | LINUXDO_USER_AGENT | Chrome 131 UA | UA for TLS transport requests | | LINUXDO_PLAYWRIGHT_FALLBACK | true | Enable Playwright fallback (auto-disabled when CDP is on) | | LINUXDO_PLAYWRIGHT_CHANNEL | chrome | Playwright browser channel | | LINUXDO_PLAYWRIGHT_HEADLESS | true | Headless mode for Playwright | | LINUXDO_PLAYWRIGHT_NAVIGATION_TIMEOUT_MS | 60000 | Playwright CF wait timeout (ms) | | LINUXDO_CDP_USER_DATA_DIR | ~/.cache/linuxdo-mcp/chrome-profile | Chrome profile directory (separate from your main Chrome to avoid profile lock conflicts) |

When CDP fallback is enabled, Playwright fallback is automatically skipped to avoid opening two browser windows.

Development

pnpm install
pnpm typecheck        # type checking
pnpm build            # compile TypeScript
npx vitest run        # run tests (158 tests)

Release

pnpm build:publish    # compile + obfuscate
pnpm publish:check    # dry-run
pnpm publish          # publish to npm

References

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

License

MIT