first-epss-mcp-server

---

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

Tool	Description
epss_get_scores	Fetch current or historical EPSS probability and percentile for supplied CVEs
epss_get_timeseries	Inspect daily history, exact-date changes, peaks, gaps, and model transitions
epss_query_threshold	Discover CVEs by inclusive score bounds, CVE year, or recent dataset addition
epss_prioritize_cves	Assign configurable remediation tiers using EPSS and caller-supplied CVSS severity
epss_list_reference	Explain score interpretation, models, coverage, and prioritization conventions

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 EPSS descending order: 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

Public Hosted Instance

A public instance is available at https://first-epss.caseyjhand.com/mcp — no installation required. It serves Streamable HTTP; each client takes its own config shape.

For Claude Code:

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

For Cline (cline_mcp_settings.json):

{
  "mcpServers": {
    "first-epss-mcp-server": {
      "type": "streamableHttp",
      "url": "https://first-epss.caseyjhand.com/mcp"
    }
  }
}

For Cursor (mcp.json):

{
  "mcpServers": {
    "first-epss-mcp-server": {
      "url": "https://first-epss.caseyjhand.com/mcp"
    }
  }
}

Claude Desktop adds remote servers under Settings → Connectors.

Self-Hosted / Local

Add the following to your MCP client configuration file.

{
  "mcpServers": {
    "first-epss-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/first-epss-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

Or with npx (no Bun required):

{
  "mcpServers": {
    "first-epss-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/first-epss-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

Or with Docker:

{
  "mcpServers": {
    "first-epss-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/first-epss-mcp-server:latest"]
    }
  }
}

For Streamable HTTP, set the transport and start the server:

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

Prerequisites

• Bun v1.4.0 or higher (or Node.js v24+).
• Internet access to FIRST's public EPSS API; no API key or account is required.

Installation

1. Clone the repository:

git clone https://github.com/cyanheads/first-epss-mcp-server.git

2. Navigate into the directory:

cd first-epss-mcp-server

3. Install dependencies:

bun install

4. Configure environment:

cp .env.example .env
# Optional: edit framework transport, auth, logging, and telemetry settings

Configuration

No server-specific settings are required.

Variable	Description	Default
MCP_TRANSPORT_TYPE	Transport: stdio or http.	stdio
MCP_HTTP_HOST	HTTP bind address.	127.0.0.1
MCP_HTTP_PORT	HTTP server port.	3010
MCP_HTTP_ENDPOINT_PATH	HTTP MCP endpoint path.	/mcp
MCP_SESSION_MODE	HTTP session mode: stateless, stateful, or auto.	auto; .env.example and Docker select stateless
MCP_AUTH_MODE	Authentication: none, jwt, or oauth.	none
MCP_LOG_LEVEL	Log level (debug, info, warning, error, etc.).	debug; client examples and Docker select info
LOGS_DIR	Directory for log files (Node.js only).	<app-root>/logs
STORAGE_PROVIDER_TYPE	Storage backend: in-memory, filesystem, supabase, cloudflare-kv/r2/d1.	in-memory
OTEL_ENABLED	Enable OpenTelemetry.	false

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

Running the server

Local development

• Build and run the production version:

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

• Run checks and tests:

  bun run devcheck  # Lints, formats, type-checks, and more
  bun run test      # Runs the test suite
  

Project structure

Directory	Purpose
src/mcp-server/tools	Five tool definitions, shared schemas, formatting, and history policy.
src/services/epss	FIRST API requests, normalization, pacing, retries, and model metadata.
tests/	Unit and integration tests mirroring the src/ 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.