echelongraph-mcp

# EchelonGraph MCP server

**CVE and internet-exposure data** for Claude, Cursor, VS Code, Cline, and any
[MCP](https://modelcontextprotocol.io) client, straight from
[EchelonGraph](https://echelongraph.io)'s free public feed.

It exposes EchelonGraph's CVE Pulse (NVD + MITRE-CNA *pre-NVD* + CISA-KEV + EPSS + GitHub
GHSA, fused into one score) **plus a per-CVE internet-exposure footprint**: how many
internet-facing services (distinct ip:port) EchelonGraph's KEV-exposure radar has on record
running a version that maps to the CVE. Exposure counts are derived from Shodan data.
Shodan data is owned by Shodan, which holds its copyright (© Shodan).

Its 14 tools look up one CVE (record, exploit code and fixed versions, EPSS history, vendor
advisories, exposure footprint), list CISA's newest KEV additions, check whether a product or
package version is affected, check an SBOM, and read a CWE and its CVEs. Every result says how
it was measured (`state`, `measured_at`, `method`, `coverage`, `freshness`, `notes`), so a model
cannot mistake an outage or an unassessed lookup for an all-clear.

It also serves four prompts, ready-made workflows a client can show as slash commands
(`triage_cve`, `kev_weekly_brief`, `am_i_affected`, `sbom_review`; see "Prompts"), and three
resources (`echelongraph://methodology`, `echelongraph://sources` and `cve://{cve_id}`; see
"Resources").

Free and keyless: no API key, no auth, read-only. The server makes no request other than the
API call a tool needs to answer.

- npm: [`echelongraph-mcp`](https://www.npmjs.com/package/echelongraph-mcp) · Official MCP
  Registry: `io.echelongraph/echelongraph-mcp` · Docs: <https://echelongraph.io/pulse/mcp>
- Source: <https://github.com/echelongraph/echelongraph-mcp> · Changes:
  [CHANGELOG.md](CHANGELOG.md) · Security: [SECURITY.md](SECURITY.md)
- Also listed on: [Smithery](https://smithery.ai/servers/echelongraph/echelongraph-mcp) ·
  [Glama](https://glama.ai/mcp/servers/echelongraph/echelongraph-mcp)

## Quick start

The local server runs through `npx` and needs Node.js 20 or later; nothing is installed
globally. Add one of the blocks below to your client, restart it, then ask: *"Is
CVE-2023-44487 actively exploited, and how many exposed services does EchelonGraph's radar
have on record for it?"*

### Claude Desktop

Two ways in. The first needs nothing installed; the second runs the server on your machine.

**1. Custom connector (no install).** Claude Desktop uses your claude.ai account's connectors:
Customize → Connectors → **+ Add** → **Add custom connector**. Name it `EchelonGraph`, paste
`https://mcp.echelongraph.io/mcp`, choose **No sign in**, and add it. No Node.js, no PATH and no
JSON to edit. A connector added on claude.ai shows up in Claude Desktop too, and the plan rules
are claude.ai's (see "Remote (no install)" below).

**2. Local server through `npx`.**

1. **Check Node.js.** In Terminal (macOS) or PowerShell (Windows), run `node -v`. It must print
   `v20` or later. If it prints an older version or `command not found`, install the LTS release
   from <https://nodejs.org>, or on macOS with Homebrew run `brew install node`.
2. **Open the config file in a plain-text editor.** Settings → Developer → Edit Config shows
   `claude_desktop_config.json` (macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`;
   Windows: `%APPDATA%\Claude\claude_desktop_config.json`). Open it in a plain-text editor such as
   VS Code, Notepad or `nano`. TextEdit on macOS turns `"` into curly quotes (`“ ”`) when Smart
   Quotes is on, and the JSON then breaks without an error: turn it off under Edit → Substitutions
   → Smart Quotes, or use another editor.
3. **Merge, do not replace.** The file usually exists already and holds Claude Desktop's own
   settings (for example a `"preferences"` object). Keep everything in it. Add an `"mcpServers"`
   key at the top level, next to the keys already there; if `"mcpServers"` is already there, add
   the `"echelongraph"` entry inside it. Mind the comma between entries. The result looks like
   this, with your own settings where `preferences` is:

   ```json
   {
     "preferences": {
       "…": "the settings already in your file stay as they are"
     },
     "mcpServers": {
       "echelongraph": {
         "command": "npx",
         "args": ["-y", "echelongraph-mcp"]
       }
     }
   }
   ```

   To check that the file parses, run
   `node -e "JSON.parse(require('fs').readFileSync(process.argv[1], 'utf8'))" "<path to the file>"`:
   no output means valid JSON.
4. **Quit fully, then reopen.** Closing the window leaves the old config loaded. On macOS choose
   Claude → Quit Claude (⌘Q); on Windows right-click the Claude icon in the system tray and choose
   Quit. The first start can take longer while `npx` downloads the package.
5. **Check that it worked.** Settings → Developer lists `echelongraph` as running, and the tools
   menu in the chat box lists EchelonGraph's 14 tools. Then ask the question at the top of this
   section.

#### Troubleshooting Claude Desktop

- **`spawn npx ENOENT`** (or the server shows as failed). On macOS, an app opened from the Dock
  does not get your shell's PATH, so Claude Desktop cannot find `npx` where Homebrew (Apple
  silicon: `/opt/homebrew/bin`; Intel: `/usr/local/bin`) or nvm put it. Run `which npx` in
  Terminal, then give Claude Desktop that absolute path as `"command"`, and the folder it is in as
  `PATH` under `"env"` (`npx` starts `node` from that same folder). With Homebrew on Apple silicon:

  ```json
  {
    "mcpServers": {
      "echelongraph": {
        "command": "/opt/homebrew/bin/npx",
        "args": ["-y", "echelongraph-mcp"],
        "env": { "PATH": "/opt/homebrew/bin:/usr/bin:/bin" }
      }
    }
  }
  ```

  With nvm, use the full path `which npx` prints (JSON does not expand `~`). Then quit fully and
  reopen. On Windows, install Node.js with the installer from nodejs.org, which adds `npx` to the
  system PATH, then quit Claude Desktop fully and reopen it.
- **The server does not appear at all.** The file is not valid JSON (a missing comma, or curly
  quotes), or the app was not fully quit: see steps 2 to 4.
- **Logs.** macOS: `~/Library/Logs/Claude/mcp-server-echelongraph.log` (this server's output) and
  `~/Library/Logs/Claude/mcp.log` (connections). Windows: `%APPDATA%\Claude\logs\`, with the same
  file names.

### Claude Code

```bash
claude mcp add --transport stdio echelongraph -- npx -y echelongraph-mcp
```

Add `--scope user` before the `--` to make it available in every project, or `--scope project`
to share it through the project's `.mcp.json`.

### Cursor

`~/.cursor/mcp.json` (every project) or `.cursor/mcp.json` (one project):

```json
{
  "mcpServers": {
    "echelongraph": {
      "command": "npx",
      "args": ["-y", "echelongraph-mcp"]
    }
  }
}
```

### VS Code

`.vscode/mcp.json` in the workspace (VS Code's key is `servers`, not `mcpServers`):

```json
{
  "servers": {
    "echelongraph": {
      "command": "npx",
      "args": ["-y", "echelongraph-mcp"]
    }
  }
}
```

or from a terminal:

```bash
code --add-mcp '{"name":"echelongraph","command":"npx","args":["-y","echelongraph-mcp"]}'
```

### Windsurf, Cline and other clients

Clients that read an `mcpServers` block (Windsurf's `mcp_config.json`, Cline's MCP settings,
and most others) take the same block as Cursor above.

### Remote (no install)

The same 14 tools, four prompts and three resources are served over Streamable HTTP at:

```text
https://mcp.echelongraph.io/mcp
```

Keyless, no sign-in, stateless; both protocol eras. The hosted endpoint is in service:
`https://mcp.echelongraph.io/health` answers `{"status":"ok","version":…}` with the package
version it runs.

- **claude.ai** (Free, Pro, Max, Team and Enterprise plans):
  Customize → Connectors → **+ Add** → **Add custom connector**. Name it `EchelonGraph`, paste
  the URL, choose **No sign in**, and add it. On Team and Enterprise an Owner adds it for the
  organization first, and each member then connects it. Free plans allow one custom connector.
- **Claude Code**:

  ```bash
  claude mcp add --transport http echelongraph https://mcp.echelongraph.io/mcp
  ```

- **Cursor** (`mcp.json`):

  ```json
  { "mcpServers": { "echelongraph": { "url": "https://mcp.echelongraph.io/mcp" } } }
  ```

- **VS Code** (`.vscode/mcp.json`):

  ```json
  { "servers": { "echelongraph": { "type": "http", "url": "https://mcp.echelongraph.io/mcp" } } }
  ```

- **Windsurf** (`mcp_config.json`):

  ```json
  { "mcpServers": { "echelongraph": { "serverUrl": "https://mcp.echelongraph.io/mcp" } } }
  ```

The hosted endpoint runs this package's code (`dist/http.js`, below) against the same public
API, so its answers are the npm package's answers. What it sees and logs is under "Privacy",
and its per-client limit under "Rate limits".

## Tools

Every tool is read-only (`readOnlyHint: true`) and declares a title and an `outputSchema`.
The example questions are ones a client can answer with that tool alone.

| Tool | Title | What it answers | Example question |
|---|---|---|---|
| `cve_summary` | CVE feed summary | Counts of active CVEs by severity band, the count with no severity band from any source (`summary.none`, sent again as `summary.unscored`: CVEs not yet scored, not a rating of None), the same CVEs counted by NVD's severity label, as provenance (`summary.nvd_critical` to `summary.nvd_none`), the rejected (withdrawn) records outside the total (`summary.rejected`), and when the feed was last updated. | *How many critical CVEs does the feed hold, and when was it last updated?* |
| `search_cves` | Search CVEs | Search/filter CVEs (severity, min CVSS, text, sort) with EchelonGraph scores and `score_assessed`; page with `limit` and `offset`; the note names each row not yet scored. | *Find critical CVEs that mention Tomcat with a CVSS of 9 or more.* |
| `get_cve` | CVE detail | One CVE's record: CVSS v3 and (when scored) v4, the