first-epss-mcp-server

Public Hosted Server: https://first-epss.caseyjhand.com/mcp

Overview

Daily forecasts of observed CVE exploitation within the next 30 days from FIRST EPSS, generated by Empirical Security and published by FIRST. Look up scores, inspect daily movement, discover CVEs by score or year, and combine likelihood with caller-supplied CVSS severity. The public API needs no key or registration.

Tools

Skills

Served over MCP as skill://first-epss-guide/SKILL.md and shipped in the npm package under skills/.

Related MCP server: vuln-priority

Capability reference

epss_get_scores tool

• Up to 5,000 cves as an array or a whitespace/comma/semicolon-delimited string; case and Unicode dashes are normalized. Process up to 500 unique identifiers from batchOffset (default 0). Optional date (2021-04-14 through today, UTC) selects a historical snapshot; omitted or blank means latest available

• Each score carries epss, percentile, date, and modelVersionSource (csv_header, published_schedule, or unavailable), ordered by EPSS descending

• unscoredCves separates invalid_format from not_returned; a missing score is unknown, never zero

• snapshot_unavailable identifies a dated snapshot FIRST cannot supply; select another date or omit it. A CVE omitted from a published snapshot remains not_returned

epss_get_timeseries tool

• Same cves / date / batchOffset inputs; process up to 50 unique identifiers per call

• Each item pairs the anchor current with up to 30 preceding daily observations in series, plus missingDates, peak, and delta7d / delta30d, which need an exact calendar baseline and otherwise appear in unavailableDeltas

• modelBoundariesCrossed and each comparison's crossesModelBoundary flag published model transitions; neither explains why a score moved

• Derived deltas are rounded to nine decimals; original scores retain their precision. Re-anchor on previousAnchorDate for the preceding window without overlap; the pointer does not guarantee a published snapshot

epss_query_threshold tool

• Inclusive minEpss / maxEpss / minPercentile / maxPercentile bounds, year, and addedWithinDays intersect, with optional historical date; at least one filter and ordered bounds are required, otherwise invalid_filter_combination. addedWithinDays is dataset-addition recency and ignores date

• One candidate page per call in FIRST's upstream order, which is not ranked by EPSS: to rank, narrow the bounds, page through every match, and sort locally. Positive safe-integer limit (default 100) plus offset. Limits above 10,000 are clamped to 10,000; the notice reports requested/applied values and both filters.limit and pagination.limit echo the applied limit. With year, candidateTotal counts broad candidates and total is null (totalRelation: "unknown"), so a filtered page can be empty with hasMore: true

• Complete score rows fit within the 65,536-byte limit on each serialized response surface. When rows are withheld, pagination.budgetLimited is true and withheldCount counts inspected matches omitted; examinedCount still counts every inspected candidate. nextOffset resumes at the first withheld match's original candidate position, including with year filtering

• Continue with the same filters and limit, provenance.scoreDates[0] as date, and nextOffset as offset

epss_prioritize_cves tool

• Up to 5,000 { cve, cvssBaseScore? } entries (CVSS 0–10, caller-supplied) against latest or optional dated EPSS; process up to 500 unique CVEs from batchOffset. A duplicate CVE with differing CVSS, including missing versus supplied, fails as conflicting_cvss. Unavailable dated snapshots fail as snapshot_unavailable

• Defaults severityThreshold: 7 and likelihood: { metric: "epss", threshold: 0.10 }, both inclusive; metric: "percentile" is an explicit alternative, and neither is FIRST guidance

• Tiers are act_now (high severity, high likelihood), scheduled (high, low), monitor (low, high), and defer (low, low); missing CVSS lands in epssOnly, missing EPSS in unscoredCves with its CVSS kept

epss_list_reference tool

• topic: interpretation, models, coverage, prioritization, or all (default)

• Static, source-linked guidance with a verifiedAt date; makes no upstream request

Batch continuation

All four dynamic tools bound each JSON-serialized content array and structuredContent object to 65,536 UTF-8 bytes, including notices, provenance, filters and pagination. Threshold discovery uses candidate continuation as described above; supplied-CVE tools use the batch continuation below.

Scores, timeseries and prioritization retain whole score rows, history items and unscored entries. processedCount still counts the workload processed, including invalid identifiers; returnedCount counts complete entries retained and withheldCount counts processed entries omitted by the byte limit. deferredCount counts entries never queried. withheldCves and deferredCves retain their array types; their *Complete flags explicitly identify previews when the full lists cannot fit. budgetLimited discloses any response shortening.

Malformed identifiers in unscored, withheld and deferred text are JSON string literals, escaped for Markdown. JSON decoding recovers the normalized identifier, including embedded CR, LF, tabs and backslashes; canonical CVEs remain plain identifiers. Structured identifiers are unchanged. Exhausted batch offsets report completion without upstream lookups or missing-score claims. Threshold notices distinguish a globally empty search, exhausted candidate offsets, and an exact-year page without matches, including the final page.

When nextBatchOffset is present, call the same tool with the original cves, nextBatchOffset as batchOffset, and provenance.scoreDates[0] as date (retain the requested date if no score date was returned). Prioritization also keeps every original cvssBaseScore, severityThreshold and likelihood. The offset counts normalized unique identifiers in first-occurrence input order, including invalid entries; score sorting does not change it. Continue until nextBatchOffset is absent. An offset past the end returns explicit empty accounting. Lists are for inspection; continuation through the original batch preserves entries even when lists are previews.

Features

Built on @cyanheads/mcp-ts-core: stdio and Streamable HTTP transports, pluggable auth (none / jwt / oauth), swappable storage (in-memory, filesystem, Supabase, Cloudflare KV/R2/D1), structured logging with optional OpenTelemetry tracing.

FIRST EPSS-specific:

• Keyless lookup against FIRST's public API, with bounded batches rather than corpus synchronization

• Shared API request pacing, transient-failure retries, cancellation, and a 45-second whole-call deadline

• Model attribution from a matching daily CSV header or the verified published schedule for explicitly dated requests and preceding history; current-anchor verification failures remain visible

Agent-friendly output:

• Provenance: API source, retrieval time, score dates, and model metadata marked verified, inferred, or unavailable

• Explicit coverage: missing EPSS and CVSS remain unknown; unscoredCves and deferredCves distinguish omissions from work not queried. Transport failures fail the call

• Structured results and formatted text carry the same accounting, history gaps, pagination, thresholds, and recovery guidance

Getting started

Connect to the hosted instance, no install:

claude mcp add --transport http first-epss-mcp-server https://first-epss.caseyjhand.com/mcp

Or run it locally:

claude mcp add first-epss-mcp-server -- npx -y @cyanheads/first-epss-mcp-server

For other clients, add this to the MCP config file:

{
  "mcpServers": {
    "first-epss-mcp-server": {
      "command": "npx",
      "args": ["-y", "@cyanheads/first-epss-mcp-server"]
    }
  }
}

FIRST's EPSS API is keyless; the server needs only internet access to it. For Docker or a source build, see Running the server.

Configuration

No server-specific settings are required.

See .env.example for every server setting and the common framework overrides.

Running the server

Local development

Requires Bun v1.4.0 or higher (or Node.js v24+).

• Clone and install:

  git clone https://github.com/cyanheads/first-epss-mcp-server.git
  cd first-epss-mcp-server && bun install
  cp .env.example .env   # optional: framework transport, auth, logging, telemetry

• Build and run:

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:stdio
  # or
  bun run start:http   # http://localhost:3010/mcp

• Run checks and tests:

  bun run devcheck   # Lint, format, typecheck, security
  bun run test       # Vitest test suite
  bun run lint:mcp   # Validate MCP definitions against spec

Docker

docker run --rm -p 3010:3010 ghcr.io/cyanheads/first-epss-mcp-server:latest

The image defaults to HTTP transport, stateless session mode, and logs to /var/log/first-epss-mcp-server. To run it over stdio from an MCP client, use "command": "docker" with "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/first-epss-mcp-server:latest"]. To build locally, docker build -t first-epss-mcp-server .; OpenTelemetry peer dependencies are installed by default — build with --build-arg OTEL_ENABLED=false to omit them.

Project structure

Development guide

See CLAUDE.md for development guidelines and architectural rules. The short version:

• Handlers throw, framework catches — no try/catch in tool logic

• Use ctx.log for logging, ctx.state for storage

• Export new tools from the src/mcp-server/tools/definitions/index.ts barrel, which src/index.ts passes to createApp()

• Wrap external API calls: validate raw → normalize to domain type → return output schema; never fabricate missing fields

Contributing

Issues are welcome. Run checks and tests before submitting:

bun run devcheck
bun run test

License

This project is licensed under the Apache 2.0 License. See the LICENSE file for details.