{
  "markdown": "# Vulners MCP Server\n\n**Vulners MCP** is a Model Context Protocol (MCP) server that provides seamless access to the Vulners vulnerability database through AI assistants like Claude Desktop. It enables security researchers and developers to query comprehensive vulnerability data, search for CVEs, analyze security bulletins, and audit software packages directly through natural language conversations.\n\n## Features\n\n- **AI Assistant Integration**: Works natively with Claude Desktop and other MCP-compatible clients\n- **Dual Transport Support**: Automatically detects and supports both stdio (for Claude Desktop) and HTTP transports\n- **Comprehensive Tools**: 7 MCP tools for vulnerability research including:\n  - Full-text Lucene search across 4M+ vulnerability bulletins\n  - CVE and bulletin information retrieval\n  - Software/package vulnerability auditing\n  - CPE search and autocomplete\n  - Linux package vulnerability auditing\n- **Flexible Deployment**: Docker, local build, or PyPI installation\n- **Environment-based Configuration**: Simple setup via environment variables\n\n## Table of Contents\n\n- [Requirements](#requirements)  \n- [Obtaining Vulners API Key](#obtaining-vulners-api-key)  \n- [Quick Start with Claude Desktop](#quick-start-with-claude-desktop)  \n- [Installation & Deployment](#installation--deployment)  \n  - [Docker with run script](#docker-with-run-script)\n  - [Docker (manual)](#docker-manual)  \n  - [Build & run locally](#build--run-locally)  \n- [Configuration / Environment Variables](#configuration--environment-variables)  \n- [Usage & Endpoints](#usage--endpoints)  \n- [Testing](#testing)\n- [Available Tools](#available-tools)\n- [Development & Contributing](#development--contributing)  \n- [License](#license)\n\n---\n\n## Requirements\n\n- Python 3.9+  \n- Access to the Vulners API (valid API key and network connectivity)  \n- (For Docker) Docker engine  \n\n---\n\n## Obtaining Vulners API Key\n\nPlease, register at [Vulners website](https://vulners.com).\nGo to the personal menu by clicking at your name at the right top corner.\nFollow \"API KEYS\" tab.\nGenerate API key with scope \"api\" and use it with the library.\n\n---\n\n## Quick Start with Claude Desktop\n\nThe easiest way to use Vulners MCP is through Claude Desktop:\n\n### 1. Build the Docker Image\n\n```bash\ngit clone https://github.com/vulnersCom/vulners-mcp.git\ncd vulners-mcp\ndocker build -t vulners-mcp:latest .\n```\n\n### 2. Configure Claude Desktop\n\nAdd to your Claude Desktop configuration file:\n\n**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`  \n**Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`  \n**Linux**: `~/.config/Claude/claude_desktop_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"vulners\": {\n      \"command\": \"docker\",\n      \"args\": [\n        \"run\",\n        \"-i\",\n        \"--rm\",\n        \"-e\",\n        \"VULNERS_API_KEY=YOUR_API_KEY_HERE\",\n        \"vulners-mcp:latest\"\n      ]\n    }\n  }\n}\n```\n\nReplace `YOUR_API_KEY_HERE` with your actual Vulners API key.\n\n### 3. Restart Claude Desktop\n\nAfter saving the configuration, restart Claude Desktop. The Vulners MCP server will be available through the 🔌 icon.\n\n### 4. Start Using\n\nYou can now ask Claude questions like:\n\n- \"Find recent vulnerabilities in Google Chrome\"\n- \"Show me details for CVE-2025-53770\"\n- \"What are recent exploted vulnerabilities in Citrix products\"\n- \"Audit this software: cpe:2.3:a:google:chrome:138.0.7204.184:*:*:*:*:*:*:*\"\n- \"Audit ubuntu 22.04 packages 'openssl 3.0.2 amd64' and 'curl 7.81.0-1ubuntu1.14 amd64'\"\n\n---\n\n## Installation & Deployment\n\n### Docker with run script\n\nFor easy HTTP mode deployment, use the provided run script:\n\n```bash\n# Create .env file with your API key\necho \"VULNERS_API_KEY=your_api_key_here\" > .env\n\n# Run the server\n./run-docker.sh\n```\n\nThe server will start in HTTP mode at <http://0.0.0.0:8000/mcp>\n\n### Docker (manual)\n\nRun the MCP server in HTTP mode:\n\n```bash\ndocker run -d \\\n  --name vulners-mcp-http \\\n  -e MCP_TRANSPORT_MODE=\"http\" \\\n  -e VULNERS_BASE_URL=\"https://vulners.com\" \\\n  -e VULNERS_API_KEY=\"your_api_key\" \\\n  -p 8000:8000 \\\n  vulners-mcp:latest\n```\n\nFor Claude Desktop (stdio mode), the `-i` flag is used instead:\n\n```bash\ndocker run -i --rm \\\n  -e VULNERS_API_KEY=\"your_api_key\" \\\n  vulners-mcp:latest\n```\n\n### Build & run locally\n\n```bash\ngit clone https://github.com/vulnersCom/vulners-mcp.git\ncd vulners-mcp\npoetry install \nexport VULNERS_API_KEY=\"your_api_key\"\npoetry run python -m vulners_mcp\n```\n\n---\n\n## Configuration / Environment Variables\n\n| Variable                       | Type    | Default               | Description                                               |\n|--------------------------------|---------|-----------------------|-----------------------------------------------------------|\n| `VULNERS_API_KEY`              | string  | *required*            | API key for authenticating with Vulners                   |\n| `VULNERS_BASE_URL`             | string  | `https://vulners.com` | Base URL for the Vulners API (without /api suffix)        |\n| `MCP_TRANSPORT_MODE`           | string  | `stdio`               | Force transport mode: `http` or `streamable-http`         |\n| `FASTMCP_HOST`                 | string  | `0.0.0.0`             | Host/interface on which MCP server binds (HTTP mode only) |\n| `FASTMCP_PORT`                 | integer | `8000`                | Port for MCP server (HTTP mode only)                      |\n| `FASTMCP_STREAMABLE_HTTP_PATH` | string  | `/mcp`                | Path for the streamable MCP endpoint (HTTP mode only)     |\n\n**Transport Mode:**\n\n- The server automatically detects the transport mode based on how it's run\n- Use `MCP_TRANSPORT_MODE=http` to explicitly force HTTP mode (for standalone HTTP server)\n- Claude Desktop uses stdio mode automatically when run with `docker run -i`\n\n---\n\n## Usage & Endpoints\n\n### With Claude Desktop\n\nSimply ask questions in natural language:\n\n- \"Search for Apache vulnerabilities\"\n- \"Get information about CVE-2024-1234\"\n- \"Audit software cpe:/a:vendor:product:version\"\n\n### HTTP Mode\n\nWhen running in HTTP mode, clients connect to:\n\n```text\nhttp://<FASTMCP_HOST>:<FASTMCP_PORT>/mcp\n```\n\nDefault: `http://0.0.0.0:8000/mcp`\n\n---\n\n## Testing\n\nTest the HTTP server using the provided test script:\n\n```bash\n# Ensure the HTTP server is running\ndocker ps | grep vulners-mcp\n\n# Run the test script\npython3 test_tools.py\n```\n\nThe test script will:\n\n1. Check server health\n2. Initialize MCP protocol\n3. List available tools\n4. Test CVE search functionality\n5. Test Lucene search\n\n---\n\n## Available Tools\n\nThe server provides 7 MCP tools for vulnerability research:\n\n### Search & Discovery\n\n- **search_lucene** - 🔍 DISCOVERY TOOL FOR UNKNOWN VULNERABILITIES 🔍 Full-text search in Vulners Knowledge Base using Lucene syntax. Use ONLY when you don't have specific IDs or version information. NEVER use for known CVE/bulletin IDs - use bulletin_by_id instead. NEVER use for specific software versions (e.g., 'Chrome 138.0.7204.184') - use audit_software instead. 🚨 CRITICAL: For vendor/product searches, ALWAYS use cnaAffected.vendor and cnaAffected.product fields - the affectedSoftware field does NOT exist.\n\n- **bulletin_by_id** - 🚨 PRIMARY TOOL FOR KNOWN IDs 🚨 Fetch full bulletin by CVE or Vulners ID. Use this when you have a specific identifier like CVE-2024-1234, RHSA-2024:001, CTX694938, etc. Supports single ID or list of IDs. When list is provided, references are automatically set to False. NEVER use search_lucene for known IDs.\n\n- **query_autocomplete** - Autocomplete helper for search inputs (vendors, products, CVEs, etc.). Get search suggestions from the Vulners database.\n\n- **search_cpe** - Find CPE strings by vendor+product (latest schema). Search for Common Platform Enumeration identifiers in the Vulners database.\n\n### Vulnerability Auditing\n\n- **audit_software** - 🔍 VERSION-SPECIFIC SOFTWARE AUDIT 🔍 Audit specific software versions for known vulnerabilities. Use this when you have exact software version information (e.g., Chrome 138.0.7204.184). NEVER use search_lucene for version-specific software audits.\n\n- **audit_linux_packages** - Linux package audit (RPM/DEB) for a given distro + version. Analyze Linux package vulnerabilities against the Vulners database.\n\n### Information & System Support\n\n- **get_supported_os** - List supported OS identifiers/versions for Linux package audit. Get available operating systems for vulnerability analysis.\n\n### Tool Selection Guidelines\n\n### 🚨 CRITICAL TOOL SELECTION RULES 🚨\n\n#### WHEN TO USE EACH TOOL\n\n- **bulletin_by_id**: Use when you have SPECIFIC IDs\n  - ✅ \"Analyze CVE-2025-7775\" → bulletin_by_id\n  - ✅ \"Look up CTX694938\" → bulletin_by_id  \n  - ✅ \"Tell me about CVE-2021-44228\" → bulletin_by_id\n  - ✅ Any specific CVE, RHSA, MS, CTX, NCSC, THN, etc. ID\n\n- **search_lucene**: Use ONLY for DISCOVERY when you don't have specific IDs\n  - ✅ \"Find vulnerabilities in Apache\" → search_lucene\n  - ✅ \"Show me recent CVEs\" → search_lucene\n  - ✅ \"What vulnerabilities exist in Chrome?\" → search_lucene\n  - ❌ NEVER use for known IDs - use bulletin_by_id instead\n\n- **audit_software**: Use for VERSION-SPECIFIC software audits\n  - ✅ \"Audit Chrome 138.0.7204.184\" → audit_software\n  - ✅ \"Check vulnerabilities in Firefox 120.0\" → audit_software\n  - ✅ Use when you have vendor + product + version information\n  - ❌ Don't use for vendor + product only (use search_lucene instead)\n\n**EFFICIENCY RULE**: One bulletin_by_id call is sufficient for known IDs. Do NOT follow up with search_lucene unless explicitly asked to broaden scope.\n\n### Follow-up Workflow for Audit Tools\n\n#### When using audit tools (audit_software, audit_linux_packages)\n\n- ✅ Run the audit tool to identify vulnerable software and get CVE IDs\n- ✅ Extract CVE IDs from the response vulnerabilities array\n- ✅ Use `bulletin_by_id` with the list of CVE IDs for detailed analysis\n- ✅ This provides comprehensive vulnerability information including patches, references, and exploitation data\n- ✅ Batch processing with `bulletin_by_id` is more efficient than multiple individual calls\n\nFor detailed tool documentation and parameters, use Claude's tool inspection or check the server's tool list.\n\n---\n\n## Development & Contributing\n\n- Open issues or feature requests on GitHub\n- Submit pull requests with improvements\n- Ensure compatibility with the Vulners API\n- Test both stdio (Claude Desktop) and HTTP modes\n\n### Building from Source\n\n```bash\ngit clone https://github.com/vulnersCom/vulners-mcp.git\ncd vulners-mcp\ndocker build -t vulners-mcp:latest .\n```\n\n---\n\n## License\n\nMIT\n\n---\n\n**MCP Name**: `io.github.vulnersCom/vulners-mcp`\n",
  "bytes": 10617,
  "sha": "b5c6f9036883725aadacb2d964d1fe819381a25080a73232e9e031b0e9a7eebb",
  "repo_slug": "vulnerscom/vulners-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_vulnerscom_vulners_mcp_41383367/readme"
}