Performs deterministic SEO audits, keyword research, and ranking checks using free data sources and MCP-compatible tools.
Also known as nitishagar/lumen, @lumen-seo/cli
- Stars
- 0
- Tools
- —
- Downloads, 30 days
- 195
- Latest version
- 0.3.0
- Last commit
- Nov 7, 2026
- License
- Apache-2.0
What is lumen MCP?
lumen performs deterministic SEO audits, keyword research, and ranking checks using free data sources and MCP-compatible tools.
Summary generated from the project's README
About lumen MCP server
Lumen provides a local-first SEO toolkit designed for developers and coding agents. It functions as an MCP-compatible server that can be connected via stdio or a Cloudflare Worker gateway. The system uses free data sources like PageSpeed Insights, CrUX, Google Suggest, and DuckDuckGo SERP to perform audits and research. Users must provide their own API keys via environment variables, which the server reads by name without storing or logging them.
This toolkit is built around five specific MCP tools: lumen_audit_site, lumen_page_report, lumen_keyword_ideas, lumen_rank_check, and lumen_authority. It features a crawler with 36 built-in rules and a severity scoring system to evaluate site health. Every metric returned includes its specific source and a fetch timestamp to ensure data provenance. The server is ideal for integrating SEO tasks directly into AI clients like Claude Code, Cursor, or VS Code.
What you can do with it
- 1Perform automated site auditsAsk your AI agent to run a full audit on a website to identify critical SEO issues.
- 2Conduct keyword researchUse the toolkit to generate new keyword ideas for content planning.
- 3Monitor search engine rankingsCheck how a specific keyword is currently ranking for a target URL.
- 4Analyze domain authorityRetrieve authority metrics for a specific domain using available free data providers.
Written from the project's README. Every use case is checked against a quote from it.
How to install lumen MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall lumen MCP in Claude Code
$ claude mcp add --env 'LUMEN_CRUX_KEY=<YOUR_LUMEN_CRUX_KEY>' --env 'LUMEN_OPR_KEY=<YOUR_LUMEN_OPR_KEY>' --env 'LUMEN_PSI_KEY=<YOUR_LUMEN_PSI_KEY>' lumen -- npx -y @lumen-seo/cliInstall lumen MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"lumen": {
"command": "npx",
"args": [
"-y",
"@lumen-seo/cli"
],
"env": {
"LUMEN_CRUX_KEY": "<YOUR_LUMEN_CRUX_KEY>",
"LUMEN_OPR_KEY": "<YOUR_LUMEN_OPR_KEY>",
"LUMEN_PSI_KEY": "<YOUR_LUMEN_PSI_KEY>"
}
}
}
}Install lumen MCP in VS Code
.vscode/mcp.json
{
"servers": {
"lumen": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@lumen-seo/cli"
],
"env": {
"LUMEN_CRUX_KEY": "<YOUR_LUMEN_CRUX_KEY>",
"LUMEN_OPR_KEY": "<YOUR_LUMEN_OPR_KEY>",
"LUMEN_PSI_KEY": "<YOUR_LUMEN_PSI_KEY>"
}
}
}
}Install lumen MCP in VS Code CLI
$ code --add-mcp '{"name":"lumen","type":"stdio","command":"npx","args":["-y","@lumen-seo/cli"],"env":{"LUMEN_CRUX_KEY":"<YOUR_LUMEN_CRUX_KEY>","LUMEN_OPR_KEY":"<YOUR_LUMEN_OPR_KEY>","LUMEN_PSI_KEY":"<YOUR_LUMEN_PSI_KEY>"}}'Install lumen MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"lumen": {
"command": "npx",
"args": [
"-y",
"@lumen-seo/cli"
],
"env": {
"LUMEN_CRUX_KEY": "<YOUR_LUMEN_CRUX_KEY>",
"LUMEN_OPR_KEY": "<YOUR_LUMEN_OPR_KEY>",
"LUMEN_PSI_KEY": "<YOUR_LUMEN_PSI_KEY>"
}
}
}
}Install lumen MCP in Codex
$ codex mcp add lumen --env 'LUMEN_CRUX_KEY=<YOUR_LUMEN_CRUX_KEY>' --env 'LUMEN_OPR_KEY=<YOUR_LUMEN_OPR_KEY>' --env 'LUMEN_PSI_KEY=<YOUR_LUMEN_PSI_KEY>' -- npx -y @lumen-seo/cliInstall lumen MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.lumen] command = "npx" args = ["-y", "@lumen-seo/cli"] [mcp_servers.lumen.env] LUMEN_CRUX_KEY = "<YOUR_LUMEN_CRUX_KEY>" LUMEN_OPR_KEY = "<YOUR_LUMEN_OPR_KEY>" LUMEN_PSI_KEY = "<YOUR_LUMEN_PSI_KEY>"
Install lumen MCP in Gemini CLI
$ gemini mcp add -s user -e 'LUMEN_CRUX_KEY=<YOUR_LUMEN_CRUX_KEY>' -e 'LUMEN_OPR_KEY=<YOUR_LUMEN_OPR_KEY>' -e 'LUMEN_PSI_KEY=<YOUR_LUMEN_PSI_KEY>' lumen npx -- -y @lumen-seo/cliInstall lumen MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"lumen": {
"command": "npx",
"args": [
"-y",
"@lumen-seo/cli"
],
"env": {
"LUMEN_CRUX_KEY": "<YOUR_LUMEN_CRUX_KEY>",
"LUMEN_OPR_KEY": "<YOUR_LUMEN_OPR_KEY>",
"LUMEN_PSI_KEY": "<YOUR_LUMEN_PSI_KEY>"
}
}
}
}Configuration
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.
LUMEN_PSI_KEYSecretGoogle PageSpeed Insights API key — enables the CWV lab leg of page reports. Optional; without it that leg reports not-configured.
| Name | Description | |
|---|---|---|
| LUMEN_CRUX_KEY | Chrome UX Report API key — enables field CWV data. Optional; without it that leg reports not-configured. | Secret |
| LUMEN_OPR_KEY | Open PageRank API key — enables the OPR authority signal. Optional; without it that signal reports not-configured. | Secret |
| LUMEN_PSI_KEY | Google PageSpeed Insights API key — enables the CWV lab leg of page reports. Optional; without it that leg reports not-configured. | Secret |
Automated checks
Ran Nov 14, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablenitishagar/lumen is public and reachablegithub.com/nitishagar/lumen ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)No build attestation published for this releaseNot checked
- Open source license (OSI)Apache-2.0spdx.org/licenses/Apache-2.0.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-07github.com/nitishagar/lumen ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from @lumen-seo/cliPass
- No critical advisory in the package or its dependencies197 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHublumen
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 (
0pass,1findings,2usage/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
| Package | Purpose |
|---|---|
@lumen-seo/core |
types + payload models, config loader (failThreshold), Fetcher (SSRF/timeout/backoff), robots, provider/rule SPIs + registries |
@lumen-seo/audit |
bounded crawler, 36 built-in AuditRules, severity scorer, report assembly |
@lumen-seo/providers |
built-in data providers (BYOK, free services only) |
@lumen-seo/cli |
lumen CLI, JSONL history, stdio MCP launcher |
@lumen-seo/mcp |
MCP tool definitions + transport adapters (Cloudflare Worker) |
@lumen-seo/site |
docs site (live) |
Note on packaging: npm packages ship compiled JavaScript + type declarations (
dist/) — plainnodeimport, no flags, notsx. The TypeScript sources stay the source of truth in the repo; the release pipeline compiles per package at publish time.
Documentation
- Quickstart — first audit, JSON output, CI usage
- CLI reference — all thirteen commands and flags
- Rules reference — the 36 rules, severities, scoring
- Providers & BYOK — data sources, keys, rate-limit etiquette
- MCP onboarding — Claude, Cursor, VS Code, remote gateway
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
lumen MCP questions
How do I add lumen MCP to Claude Code?
Run claude mcp add --env 'LUMEN_CRUX_KEY=<YOUR_LUMEN_CRUX_KEY>' --env 'LUMEN_OPR_KEY=<YOUR_LUMEN_OPR_KEY>' --env 'LUMEN_PSI_KEY=<YOUR_LUMEN_PSI_KEY>' lumen -- npx -y @lumen-seo/cli in your terminal. Add --scope user to make it available in every project.
How do I add lumen MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What kind of SEO audits does lumen provide?
It provides local site audits using a crawler with 36 built-in rules, severity scoring, and CI-friendly exit codes.
How does lumen handle API keys for data providers?
It uses a 'Bring Your Own Key' (BYOK) model where keys are read from environment variables by name and are never stored or logged.
What MCP tools are available in lumen?
The toolkit includes five MCP tools: lumen_audit_site, lumen_page_report, lumen_keyword_ideas, lumen_rank_check, and lumen_authority.