Cisco PSIRT OpenVuln MCP 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

Related MCP server: NVD MCP Server

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

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:

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.