OpenVAS MCP Server

MCP server for Greenbone Vulnerability Management (GVM/OpenVAS), written in Rust. A thin, typed MCP front end over the rust-gvm-api REST gateway: all GMP/gvmd knowledge lives in the gateway, this server maps MCP tools onto gateway HTTP endpoints.

MCP client (Claude, etc.)
        │  stdio / streamable HTTP
        ▼
      gvm-mcp  (this repo, single binary)
        │  HTTP/JSON — forwards the caller's gvmd identity
        ▼
  rust-gvm-api REST gateway  (/api/v1)
        │  GMP over Unix socket
        ▼
      gvmd

Quick start

Docker (streamable HTTP)

docker run --rm \
  -e GVM_GATEWAY_URL=http://gateway:8080 \
  -e GVM_USERNAME=admin \
  -e GVM_PASSWORD=secret \
  -p 127.0.0.1:8000:8000 \
  ghcr.io/greenbone-hive/openvas-mcp-server:latest

MCP endpoint: http://localhost:8000/mcp. A full stack example (gateway + gvmd socket wiring) is in docker-compose.example.yml.

Binary (stdio)

Download a release binary (or cargo build --release), then register it with your MCP client:

{
  "mcpServers": {
    "openvas": {
      "command": "/path/to/gvm-mcp",
      "env": {
        "GVM_GATEWAY_URL": "http://localhost:8080",
        "GVM_USERNAME": "admin",
        "GVM_PASSWORD": "secret"
      }
    }
  }
}

Start with the openvas_test_connection tool — it checks gateway liveness, the gvmd version and makes one authenticated call to confirm the identity is accepted.

Authentication

gvm-mcp holds no session and invents no auth of its own — it forwards a caller's gvmd identity to the gateway, and the gateway (backed by gvmd) is the sole authority. The Authorization used for each gateway call is resolved per request:

1. the inbound MCP request's Authorization header, when present — so each streamable-HTTP caller authenticates as themselves (send Basic gvmd credentials, or a gateway session token you obtained); otherwise
2. a fallback Basic header built from configured GVM_USERNAME / GVM_PASSWORD — used for stdio, and for HTTP callers that send none.

If neither is available, gateway calls go out unauthenticated and are rejected with 401, surfaced as a legible tool error. No credentials are ever cached as a session; --username/--password are optional (omit them to require every HTTP caller to authenticate as themselves).

--allowed-hosts is a DNS-rebinding guard, not authentication. For a public HTTP deployment, terminate TLS and (if you want a single shared identity) authenticate at a reverse proxy in front.

Configuration

Every flag has an environment variable.

| Flag | Env | Default | Purpose | | ---- | --- | ------- | ------- | | --gateway-url | GVM_GATEWAY_URL | http://127.0.0.1:8080 | rust-gvm-api origin (without /api/v1) | | --username | GVM_USERNAME | — | gvmd username for the fallback identity (optional) | | --password | GVM_PASSWORD | — | gvmd password for the fallback identity (optional) | | --password-file | GVM_PASSWORD_FILE | — | file containing the password (takes precedence) | | --transport | MCP_TRANSPORT | stdio | stdio or streamable-http | | --bind-addr | MCP_BIND_ADDR | 127.0.0.1:8000 | HTTP bind address | | --allowed-hosts | MCP_ALLOWED_HOSTS | localhost,127.0.0.1,::1 | Host-header allow list (* disables) | | --toolsets | GVM_TOOLSETS | default | comma-separated toolset selection | | --read-only | GVM_READ_ONLY | false | expose only non-mutating tools | | --timeout-secs | GVM_HTTP_TIMEOUT | 30 | gateway HTTP timeout | | --log-level | GVM_LOG_LEVEL | info | log level when RUST_LOG unset |

Toolsets

The full surface is 104 tools — far too many to hand an LLM by default, so tools are grouped into toolsets (gvm-mcp --list-toolsets prints them all). The default selection is every toolset except identity; add it explicitly with --toolsets default,identity. --read-only additionally strips every mutating tool from the listing.

| Selection | Tools | | --------- | ----- | | default | 81 | | default, read-only | 49 | | default + identity | 104 |

Highlights:

• targets / tasks — CRUD plus the scan lifecycle (openvas_start_task → report UUID, stop, resume).
• reports — list/get, drill-down pages (results, vulnerabilities, errors, closed CVEs, TLS certificates) and asynchronous exports: openvas_export_report → poll openvas_get_job → openvas_download_job_result (JSON inline, binary formats base64 up to 3 MB).
• scan-configs / scanners / schedules / credentials / alerts / port-lists / notes / overrides — reads everywhere, writes where the gateway supports them.
• nvts / results / assets / feeds / tickets / filters / tags / report-formats — read surface with GMP filter expressions (filter: "severity>7 and host=10.0.0.5").
• identity (opt-in) — users, groups, roles, permissions, user settings.

List tools return summarized rows plus pagination to protect the model's token budget; get tools return the gateway's full JSON.

Development

cargo test                                    # unit + mock-gateway tests
cargo fmt --all && cargo clippy --all-targets --all-features -- -D warnings
cargo run -- --list-toolsets

The test suite runs entirely against a mock gateway (wiremock) — no GVM installation needed. End-to-end tests against a live stack are gated behind #[ignore]:

export GVM_E2E_GATEWAY_URL=http://localhost:8080
export GVM_USERNAME=admin GVM_PASSWORD=secret
cargo test --test e2e_live -- --ignored

DTOs and endpoint shapes mirror the gateway's spec/rest-api contract. See docs/ for detailed install/usage/development guides.

Limitations

• Requires a running rust-gvm-api gateway; the server never speaks GMP directly.
• Clone operations and ticket/filter/tag/host write tools are not exposed yet — the gateway does not serve those endpoints. They land once the gateway does.
• Compliance (audits/policies) tools depend on the gateway's compliance surface and are not yet available.

Contributing

See CONTRIBUTING.md for the development loop, how to add a tool, and PR conventions. Security issues: see SECURITY.md. Releases follow RELEASING.md.

License

AGPL-3.0-or-later.