MCP onboarding

lumen is an MCP server first. One stdio command, five tools, no account. The same server binary runs wherever Node runs.

Claude Code

one-liner


      $ claude mcp add --transport stdio lumen -- npx -y @lumen-seo/cli mcp

Verify with /mcp inside Claude Code; the five lumen_* tools should be listed.

Cursor

Add the server to .cursor/mcp.json in your project (or ~/.cursor/mcp.json globally):

{
  "mcpServers": {
    "lumen": {
      "command": "npx",
      "args": ["-y", "@lumen-seo/cli", "mcp"]
    }
  }
}

Cursor also supports one-click installs via its deeplink format (cursor://anysphere.cursor-deeplink/mcp/install?… with a base64-encoded config); the JSON block above is the same config that deeplink carries.

VS Code

Use .vscode/mcp.json:

{
  "servers": {
    "lumen": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@lumen-seo/cli", "mcp"]
    }
  }
}

VS Code offers a vscode:mcp/install?{…} deeplink that pre-fills this file; the stdio command is identical either way.

Universal JSON

For any client that speaks mcpServers:

{"mcpServers":{"lumen":{"command":"npx","args":["-y","@lumen-seo/cli","mcp"]}}}

Bundles and plugins

Claude Desktop users can install without touching any config file — the .mcpb desktop extension carries the server config and asks for the three optional keys itself (they travel to lumen as environment variables, names only, and are sent only to their own providers):

Download lumen.mcpb from https://github.com/nitishagar/lumen/releases and double-click it

Claude Code users can install lumen as a plugin, which adds the MCP server plus the seo-check skill (audit → ranked fixes → re-audit):

/plugin marketplace add nitishagar/lumen
/plugin install lumen@nitishagar-lumen

The five tools

Tool	What it does
`lumen_audit_site`	crawl a site and return the audit report (bounded, robots-safe) — local/stdio only
`lumen_page_report`	single page: PSI + CrUX when keys are configured, plus a local meta fetch
`lumen_keyword_ideas`	keyword ideas from the configured keyword provider, provenance attached
`lumen_rank_check`	best-effort SERP position for keyword + domain
`lumen_authority`	domain authority signals (Open PageRank, Tranco)

Every tool accepts an optional response_format of concise (default) or detailed. Concise is built for agents — the high-signal summary first — while detailed returns the full payload. Both carry provenance labels on every value.

Remote gateway (optional)

The repo ships a thin Cloudflare Worker that exposes the same tools over Streamable HTTP plus the REST subset (POST /mcp, GET /api/v1/page-report?url=, GET /api/v1/keyword-ideas?q=, GET /healthz). It is deployable from the free Workers tier, but nothing in lumen requires it: stdio is the primary path and the Worker is not deployed by default. BYOK keys pass per-request via headers and are never logged. Treat a self-deployed Worker as personal use — add hardening before sharing the URL:

WORKER_AUTH_TOKEN (secret) — when set, every route except preflight and /healthz requires Authorization: Bearer <token>.
WORKER_ALLOWED_ORIGINS (comma list) — when set, CORS reflects only those origins instead of the default *.

The audit stays local

lumen_audit_site is a local-only capability by design — a crawl needs CPU and politeness budgets that a shared free tier can’t offer. Over the remote gateway the tool returns a typed local-only capability error pointing at npx @lumen-seo/cli instead of silently doing less. The other tools work the same everywhere.

Keys for BYOK providers are read from the environment (LUMEN_PSI_KEY, LUMEN_CRUX_KEY, LUMEN_OPR_KEY, LUMEN_BING_KEY, LUMEN_GSC_CREDENTIALS) — see providers & BYOK.