# Voraxx MCP Server

A minimal, dependency-free [Model Context Protocol](https://modelcontextprotocol.io) (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](https://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](https://internetdb.shodan.io) 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](https://github.com/projectdiscovery/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](https://github.com/bharat3645/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.

```bash
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):

```bash
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`):

```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):

```bash
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`.