mcpField
L
lumen

lumen

Local
github.com/nitishagarBusiness & Marketing0Updated 4w ago
Repository

About lumen

lumen is a local-first SEO toolkit for site audits and coding agents, available through a CLI and MCP. It uses free data sources and records the source and fetch time for each metric.

Key features

  1. 0136-rule website audits
  2. 02Keyword ideas and rank checks
  3. 03Core Web Vitals reports
  4. 04Metric sources and timestamps
  5. 05CI-friendly exit codes

Use cases

  1. 01Find and prioritize website SEO issues
  2. 02Run site audits in CI through the CLI
  3. 03Check keyword ideas and search rankings

MCP support

It provides five MCP tools for site audits, page reports, keyword ideas, rank checks, and authority lookups. They work over stdio or through a Cloudflare Worker gateway.

Configuration

Local server config is the same for every client. Copy it into your client’s MCP config file.

mcp.json · Universal config
{
  "mcpServers": {
    "nitishagar-lumen": {
      "command": "npx",
      "args": [
        "-y",
        "@lumen-seo/cli"
      ],
      "env": {
        "LUMEN_PSI_KEY": "<LUMEN_PSI_KEY>",
        "LUMEN_CRUX_KEY": "<LUMEN_CRUX_KEY>",
        "LUMEN_OPR_KEY": "<LUMEN_OPR_KEY>"
      }
    }
  }
}
Run commandnpx -y @lumen-seo/cli
Environment variables to set
LUMEN_PSI_KEYSecretGoogle PageSpeed Insights API key — enables the CWV lab leg of page reports. Optional; without it that leg reports not-configured.
LUMEN_CRUX_KEYSecretChrome UX Report API key — enables field CWV data. Optional; without it that leg reports not-configured.
LUMEN_OPR_KEYSecretOpen PageRank API key — enables the OPR authority signal. Optional; without it that signal reports not-configured.

Local servers need a runtime on your machine (e.g. Node.js 18+). Config file locations differ by client; see your client’s docs.

Packages
npm@lumen-seo/cli0.3.0

Tools

5

Saved tool list · updated 3w ago

ParameterTypeRequiredDescription
urlstringYes
maxPagesintegerNo
failThresholdenumNoinfo | warning | error | off
response_formatenumNoconcise | detailed

Details

From the project README

lumen

CI npm Docs License: Apache-2.0

Lightweight, pluggable, MCP-first SEO toolkit — free services only, bring your own keys, provenance on every number.

Status: v0.2.x — first public release. The CLI, the five MCP tools, and the docs site are live; see CHANGELOG.md for what shipped and the docs for the full guides.

Why lumen

Most SEO tooling is a black box with a subscription. lumen is the opposite: a local-first, agent-first audit toolkit that runs on free data sources, never ships a number it can't attribute, and speaks MCP so your coding agent can run it for you.

  • Local site audits — bounded, robots-respecting crawler with 36 built-in rules, severity scoring, and CI-friendly exit codes (0 pass, 1 findings, 2 usage/abort).
  • Free-tier data providers — PageSpeed Insights, CrUX, Google Suggest, Wikipedia demand, OpenPageRank, Tranco, DuckDuckGo SERP. BYOK: keys are read from env vars by name, never stored or logged.
  • MCP-first — five tools (lumen_audit_site, lumen_page_report, lumen_keyword_ideas, lumen_rank_check, lumen_authority) over stdio or a thin Cloudflare Worker gateway.
  • Provenance on every number — each metric carries its source and fetch timestamp; no free source, no number.

Quickstart

Requires Node >= 22.7.

# One-off audit — no install
npx -y @lumen-seo/cli audit https://example.com

# Install globally
npm install -g @lumen-seo/cli
lumen audit https://example.com --max-pages 50

Wire it into Claude Code (or Cursor / VS Code — MCP onboarding):

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

Then just ask: "audit my site and tell me what to fix first."

Packages

PackagePurpose
@lumen-seo/coretypes + payload models, config loader (failThreshold), Fetcher (SSRF/timeout/backoff), robots, provider/rule SPIs + registries
@lumen-seo/auditbounded crawler, 36 built-in AuditRules, severity scorer, report assembly
@lumen-seo/providersbuilt-in data providers (BYOK, free services only)
@lumen-seo/clilumen CLI, JSONL history, stdio MCP launcher
@lumen-seo/mcpMCP tool definitions + transport adapters (Cloudflare Worker)
@lumen-seo/sitedocs site (live)

Note on packaging: npm packages ship compiled JavaScript + type declarations (dist/) — plain node import, no flags, no tsx. The TypeScript sources stay the source of truth in the repo; the release pipeline compiles per package at publish time.

Documentation

Development

Requires Node >= 22.

npm install
npm run lint
npm run typecheck
npm test

See CONTRIBUTING.md for conventions, SECURITY.md for the security policy, and docs/release.md for the release runbook.

License

Apache-2.0 — Copyright 2026 Nitish Agarwal

Comments

Markdown supported

New to MCP?

From what the protocol is to installing your first server, these answers cover most first questions.

An open protocol that defines how AI applications connect to external tools and data in a uniform way. Clients talk to the model; MCP servers provide tools, resources and prompt templates. They exchange standard messages, so one server can be reused by many clients.