recommended-by-mcp

Stdio MCP server for managing your recommended.by lists from agents like OpenClaw, Codex, Claude Desktop, Claude Code, Cursor, and Windsurf.

The package talks to the recommended.by REST API and exposes MCP tools over stdio. This is useful for clients that do not support remote HTTP MCP headers consistently: the agent launches this package locally, and the package handles recommended.by authentication.

Quick Start

Create an API key in Dashboard -> Profile & URL -> API Keys, then authenticate the package once:

npx recommended-by-mcp@latest login rb_live_your_key_here

Then configure your MCP client to run:

npx -y recommended-by-mcp@latest

You can also avoid local storage and pass the key through an environment variable:

RECOMMENDED_BY_API_KEY=rb_live_your_key_here npx -y recommended-by-mcp@latest

Authentication

The server resolves auth in this order:

1. --api-key rb_live_...
2. RECOMMENDED_BY_API_KEY
3. saved config from recommended-by-mcp login

The saved config lives at:

• macOS: ~/Library/Application Support/recommended-by-mcp/config.json
• Linux: ~/.config/recommended-by-mcp/config.json
• Windows: %APPDATA%\recommended-by-mcp\config.json

Remove the saved key with:

npx recommended-by-mcp@latest logout

Check which account the key can access:

npx recommended-by-mcp@latest whoami

MCP Tools

• recommended_list_lists
• recommended_create_list
• recommended_get_list
• recommended_update_list
• recommended_delete_list
• recommended_list_items
• recommended_search_items
• recommended_add_item_from_result
• recommended_add_item
• recommended_update_item
• recommended_delete_item

Use recommended_search_items before adding ambiguous books, places, podcasts, music, movies, or TV. It returns candidates with stable sourceId values plus preview fields. For Google Places candidates, show confirmationUrl and previewImageUrl to the user before calling recommended_add_item_from_result.

Client Examples

Codex

Add this to ~/.codex/config.toml:

[mcp_servers.recommended_by]
command = "npx"
args = ["-y", "recommended-by-mcp@latest"]
env = { RECOMMENDED_BY_API_KEY = "rb_live_your_key_here" }

OpenClaw

openclaw mcp add recommended-by \
  --command npx \
  --arg -y \
  --arg recommended-by-mcp@latest \
  --env RECOMMENDED_BY_API_KEY=rb_live_your_key_here

openclaw mcp doctor recommended-by --probe

Claude Desktop

Add this to claude_desktop_config.json:

{
  "mcpServers": {
    "recommended-by": {
      "command": "npx",
      "args": ["-y", "recommended-by-mcp@latest"],
      "env": {
        "RECOMMENDED_BY_API_KEY": "rb_live_your_key_here"
      }
    }
  }
}

Development

pnpm install
pnpm --filter recommended-by-mcp build
pnpm --filter recommended-by-mcp test