Voraxx MCP Server

A minimal, dependency-free Model Context Protocol (MCP) server that gives AI agents three real, read-only security-orchestration tools:

Tool	What it does	Requires a key?
cve_lookup	Look up a CVE by ID against OSV.dev's vulnerability database (summary, CVSS, affected packages, references)	No
shodan_host_lookup	Recon an IP (open ports, hostnames, CPEs, known CVEs) via Shodan's free InternetDB endpoint, or the full Shodan Host API if you set SHODAN_API_KEY	No (optional for the full API)
nuclei_scan	Run a scan against a target using your own locally-installed nuclei binary, and summarize the JSONL findings	No (nuclei itself is separate, free, open-source)

Why this exists

By mid-2026, wrapping recon/vuln-intel tools (Nuclei, Shodan, Nmap, CVE databases) behind MCP servers so LLM agents can call them directly — instead of shelling out ad hoc — has become a standard pattern in AI-assisted security tooling. This is a small, honest implementation of that pattern: a companion, standalone utility to the Voraxx AI pentesting agent, usable on its own with any MCP-compatible client (Claude Desktop, Claude Code, etc.).

It is deliberately minimal. It does not bundle exploit code, attack payloads, or scan templates of its own — every tool either queries a public, read-only data source, or shells out to a well-known external scanner (nuclei) that you install and control yourself.

Install

No third-party dependencies are required to run the server — it's pure Python 3.9+ standard library.

git clone https://github.com/bharat3645/voraxx-mcp-server.git
cd voraxx-mcp-server
python3 -m voraxx_mcp   # starts the MCP server on stdio

If you'd rather install it as a package (adds the voraxx-mcp-server console script):

pip install -e .
voraxx-mcp-server

Use it from an MCP client

Point your MCP client's config at this server over stdio. Example (Claude Desktop / Claude Code style config, see examples/mcp_client_config.json):

{
  "mcpServers": {
    "voraxx-security": {
      "command": "python3",
      "args": ["-m", "voraxx_mcp"],
      "cwd": "/absolute/path/to/voraxx-mcp-server",
      "env": { "SHODAN_API_KEY": "" }
    }
  }
}

Once connected, the client will see three tools — cve_lookup, shodan_host_lookup, nuclei_scan — with full JSON Schema for their arguments (tools/list), and can invoke them (tools/call) like any other MCP tool.

Environment variables

Variable	Purpose	Default
SHODAN_API_KEY	If set, shodan_host_lookup uses the full Shodan Host API instead of the free InternetDB endpoint	unset (uses free InternetDB)
VORAXX_MCP_HTTP_TIMEOUT	Timeout (seconds) for outbound HTTP lookups	10
VORAXX_MCP_OSV_BASE_URL	Override the OSV.dev base URL (mainly for testing)	https://api.osv.dev
VORAXX_MCP_SHODAN_INTERNETDB_URL	Override the InternetDB base URL (mainly for testing)	https://internetdb.shodan.io
VORAXX_MCP_SHODAN_API_URL	Override the Shodan Host API base URL (mainly for testing)	https://api.shodan.io

Safety

• Only scan or query targets and hosts you own or are explicitly authorized to test. nuclei_scan runs a real scanner against a real target you provide — this project supplies no default target and no bundled templates.
• nuclei_scan shells out to your local nuclei binary using an argument list (never a shell string), so there's no shell-injection surface from the target value.
• Nothing here writes findings anywhere but back to the calling MCP client — no telemetry, no external reporting, no persistence.
• If nuclei isn't installed, the tool says so plainly and explains how to install it, rather than failing silently or fabricating output.

Architecture

voraxx_mcp/server.py implements the minimal JSON-RPC 2.0 / stdio subset of MCP (initialize, notifications/initialized, ping, tools/list, tools/call) in about 180 lines of dependency-free Python — no mcp SDK install required. voraxx_mcp/tools.py holds the three tool implementations, and voraxx_mcp/app.py wires them together with their JSON Schemas.

This is intentionally a small, auditable core rather than a dependency on a larger SDK, so the whole request/response lifecycle is easy to read end to end in one sitting.

Testing

Two test suites, both stdlib-only (no pytest required, though it works fine too):

python3 -m unittest discover -s tests -v

• tests/test_protocol.py — spawns the server as a real subprocess and speaks actual newline-delimited JSON-RPC to it over stdin/stdout (the same transport a real MCP client uses), covering the full initialize → tools/list → tools/call lifecycle, error handling, and malformed input.
• tests/test_tools_offline.py — exercises the tool logic against a local stub HTTP server seeded with real response fixtures captured from OSV.dev and Shodan InternetDB, plus a fake nuclei binary on PATH for the scan-parsing path — so the full request → parse → format flow is verified without needing live internet access or an installed scanner.

All 19 tests pass in this repo's CI-free, offline sandbox verification; see commit history for the verification run.

Limitations (honest, as of v0.1.0)

• No caching, rate-limiting, or retry/backoff on outbound HTTP calls yet.
• nuclei_scan summarizes JSONL output; it doesn't expose every nuclei CLI flag.
• No authentication/multi-tenancy layer — this is a single-user, local stdio server, as most MCP servers are.
• Only three tools. More (e.g. Subfinder, httpx, an authenticated NVD lookup) could be added following the same pattern in voraxx_mcp/tools.py.

License

MIT — see LICENSE.