Cisco PSIRT OpenVuln Server

A production-quality Model Context Protocol (MCP) server for querying Cisco security advisories via the PSIRT OpenVuln API v2. Built with Python and FastMCP, it enables LLM-powered interfaces like Claude Desktop and Kiro to search, filter, and analyze Cisco vulnerability data.

Features

• 15 MCP tools covering all Cisco PSIRT OpenVuln API v2 endpoints
• OAuth2 authentication with automatic token caching and refresh (client_credentials flow)
• Multi-tier rate limiting — 5 calls/sec, 30 calls/min, 5,000 calls/day (client-side enforcement)
• Server-side 429 retry — automatic retry with Retry-After header support (up to 3 attempts)
• Input validation on all parameters with descriptive error messages
• Pagination support across all list endpoints (page_index, page_size)
• LLM-optimized responses — consistent structured envelope with summary truncation
• Transport-agnostic — supports stdio (default) and SSE transports
• Structured error handling — classified errors with user-friendly messages

Prerequisites

• Python 3.10+
• Cisco API Console credentials (client_id and client_secret) — see Getting Cisco API Credentials

Installation

1. Clone the repository:

   git clone <repository-url>
   cd openvuln-mcp-server
   

2. Create a virtual environment:

   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   

3. Install dependencies:

   pip install -r requirements.txt
   

4. Configure credentials:

   cp .env.example .env
   

   Edit .env and fill in your Cisco API credentials:

   CISCO_CLIENT_ID=your_client_id_here
   CISCO_CLIENT_SECRET=your_client_secret_here
   

Getting Cisco API Credentials

1. Go to the Cisco API Console and sign in (or create an account)
2. Register a new application
3. Enable the "Cisco PSIRT openVuln API" for your application
4. Copy the generated client_id and client_secret
5. Add them to your .env file or pass them as environment variables

Each user's credentials are independent — rate limits are tracked per client_id on Cisco's side.

Usage

stdio mode (default)

Standard transport for local MCP integrations (Claude Desktop, Kiro):

python main.py

SSE mode

HTTP-based Server-Sent Events transport for web or remote integrations:

python main.py --transport sse --port 8080

MCP Client Configuration

Claude Desktop / Kiro (stdio)

Add to your MCP client configuration file:

{
  "mcpServers": {
    "cisco-openvuln": {
      "command": "python",
      "args": ["main.py"],
      "cwd": "/path/to/openvuln-mcp-server",
      "env": {
        "CISCO_CLIENT_ID": "your_client_id",
        "CISCO_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}

SSE client

{
  "mcpServers": {
    "cisco-openvuln": {
      "url": "http://localhost:8080/sse"
    }
  }
}

Available Tools

#	Tool	Description	Key Parameters
1	get_all_advisories	Retrieve all published advisories with pagination	page_index, page_size
2	get_advisory_by_id	Look up a specific advisory by Cisco advisory ID	advisory_id (max 100 chars)
3	get_advisory_by_cve	Find advisories by CVE identifier	cve_id (CVE-YYYY-NNNNN format)
4	get_advisory_by_bug_id	Find advisories by Cisco Bug ID	bug_id (CSCxxNNNNN format)
5	get_latest_advisories	Get the N most recently published advisories	number (1–100, default 5)
6	get_advisories_by_severity	Filter advisories by severity level	severity (critical/high/medium/low/informational)
7	get_advisories_by_severity_first_published	Filter by severity and first-published date range	severity, start_date, end_date
8	get_advisories_by_severity_last_published	Filter by severity and last-updated date range	severity, start_date, end_date
9	get_advisories_by_first_published	Find advisories first published in a date range	start_date, end_date (YYYY-MM-DD)
10	get_advisories_by_last_published	Find advisories last updated in a date range	start_date, end_date (YYYY-MM-DD)
11	get_advisories_by_product	Search advisories by product name	product_name
12	get_advisories_by_year	Get advisories published in a specific year	year (1995–current)
13	get_advisories_by_os_version	Find advisories for a specific OS type and version	os_type, version, platform_alias (optional)
14	get_os_version_data	Get available OS version metadata	os_type
15	get_platform_aliases	List platform aliases for an OS type	os_type (nxos/asa/ftd/fxos only)

All list-returning tools support page_index (1–100) and page_size (1–100) pagination parameters.

Running Tests

Run the full test suite:

pytest

Run with coverage:

pytest --cov=src --cov-report=term-missing

Run a specific test file:

pytest tests/test_validators.py

Run property-based tests (Hypothesis):

pytest tests/ -k "property"

Rate Limits

The server enforces client-side rate limiting to stay within Cisco API quotas:

Tier	Limit	Enforcement
Per-second	5 calls/sec	Minimum 200ms between requests
Per-minute	30 calls/min	Rolling 60-second sliding window
Per-day	5,000 calls/day	Calendar day counter, resets at 00:00 UTC

When a rate limit is hit:

• Per-second / per-minute: The server automatically sleeps until the next request is permitted
• Per-day: Returns an error indicating the daily limit is exhausted, with seconds until reset
• Server-side 429: Retries up to 3 times using the Retry-After header (default 60s if absent)

Project Structure

openvuln-mcp-server/
├── main.py                    # Entry point: loads env, parses args, starts server
├── src/
│   ├── __init__.py
│   ├── server.py              # FastMCP server and 15 tool registrations
│   ├── oauth2_client.py       # OAuth2 client_credentials with token caching
│   ├── rate_limiter.py        # Multi-tier rate limiter
│   ├── api_client.py          # HTTP client with auth, rate limiting, retry
│   ├── validators.py          # Input validation functions
│   ├── response_formatter.py  # LLM-optimized response formatting
│   ├── constants.py           # URLs, limits, validation rules
│   └── exceptions.py          # Custom exception hierarchy
├── tests/
│   ├── test_validators.py
│   ├── test_oauth2_client.py
│   ├── test_rate_limiter.py
│   ├── test_api_client.py
│   ├── test_response_formatter.py
│   └── test_tools.py
├── .env.example               # Credentials template
├── requirements.txt           # Python dependencies
└── README.md

License

This project is licensed under the Apache License 2.0.