linuxdo

linuxdo is a JSON-first CLI for Linux.do and a stdio MCP server powered by the same tool catalog. Use it directly from the terminal, or expose the same forum operations to AI clients with linuxdo mcp serve.

Features

• Shared CLI + MCP tool catalog from one definition source
• Canonical CLI tree for agents and scripts: topics, notifications, bookmarks, messages
• MCP server with 6 forum tools: topics, search, notifications, bookmarks, private messages
• Interactive auth flow for Linux.do user API keys
• JSON-first command behavior with discovery surfaces: tools, describe, call
• Automatic Cloudflare handling with TLS, Playwright, and real Chrome CDP fallback
• linuxdo doctor for runtime checks and optional live API verification

Install

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

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

Quick Start

Use as CLI

Generate a Linux.do user API key:

linuxdo auth

The auth flow prints an authorization URL, opens a browser when possible, asks you to paste the response payload back into the terminal, and then prints your API key and username. Export the result in your shell:

export LINUXDO_USER_API_KEY=your-api-key
export LINUXDO_USERNAME=your-username

Verify the setup and make a first request:

linuxdo doctor --verify-api
linuxdo topics list --filter latest
linuxdo topics search --term "MCP in:title"

Use as MCP

Add linuxdo to your MCP client config:

{
  "mcpServers": {
    "linuxdo": {
      "command": "linuxdo",
      "args": ["mcp", "serve"],
      "env": {
        "LINUXDO_USER_API_KEY": "your-api-key",
        "LINUXDO_USERNAME": "your-username"
      },
      "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.

Canonical command tree

linuxdo topics list --filter latest
linuxdo topics read --topic-id 1465729
linuxdo topics search --term "MCP in:title"
linuxdo notifications list --limit 20
linuxdo bookmarks list
linuxdo messages list

Static commands

linuxdo auth
linuxdo doctor --verify-api
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 Overview

linuxdo mcp serve starts a stdio MCP server using the same shared catalog as the CLI.

| MCP tool | CLI path | Purpose | | --- | --- | --- | | list_topics | linuxdo topics list | List topics by filter such as latest, hot, top, or category | | read_topic | linuxdo topics read | Read a topic and its replies | | search_topics | linuxdo topics search | Search with Discourse syntax such as in:title and category: | | get_notifications | linuxdo notifications list | Fetch recent notifications | | get_bookmarks | linuxdo bookmarks list | Fetch bookmarked posts | | get_messages | linuxdo messages list | Fetch private messages |

Runtime Notes

Required environment

| Variable | Description | | --- | --- | | LINUXDO_USER_API_KEY | Discourse User API key | | LINUXDO_USERNAME | Your Linux.do username |

Cloudflare handling

Linux.do is protected by Cloudflare. linuxdo handles this automatically with a 3-stage fallback chain:

1. TLS transport with a Chrome-like fingerprint
2. Playwright fallback when TLS is blocked
3. Real Chrome CDP fallback for interactive verification

When CDP fallback is required, a real Chrome window opens so you can finish the challenge manually. The verified session is then reused, and the dedicated Chrome profile is cached under ~/.cache/linuxdo-mcp/chrome-profile by default.

Selected optional environment variables

| Variable | Default | Purpose | | --- | --- | --- | | LINUXDO_PROXY_URL | unset | HTTP proxy for outbound requests | | LINUXDO_CDP_FALLBACK | true | Enable real Chrome CDP fallback | | 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-mcp/chrome-profile | Override the dedicated Chrome profile directory |

Development

pnpm install
pnpm typecheck
pnpm build
npx vitest run

References

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

License

MIT