GreenboneMCP

An MCP (Model Context Protocol) server that connects AI clients to Greenbone/OpenVAS through GMP (python-gvm).

What this project is

GreenboneMCP exposes MCP tools for scan/report workflows in Greenbone/OpenVAS, so an assistant can:

• create and launch scans,
• monitor scan progress,
• stop scans,
• fetch reports,
• compare report deltas between runs.

The server runs on stdio transport and talks to gvmd through a Unix socket.

Project status

This project is part of my Master's thesis and is currently a Proof of Concept (PoC).

It may be developed further only if there is clear community/user interest.

Contributions are welcome: feel free to open Issues and submit Pull Requests. (See the Contributing section below.)

Tooling exposed by the server

Scan workflow tools

These are always registered:

• start_scan
• scan_status
• fetch_latest_report
• restart_scan
• delta_report

Inspection / control tools

These are always registered:

• get_targets
• get_target
• get_tasks
• get_port_lists
• start_task
• stop_task

Project Structure

src/
├── main.py                     # App entrypoint (stdio MCP server)
├── constants.py                # Default UUIDs and report format constants
├── config/
│   ├── gvm_client_config.py    # Env-based GVM client settings (USERNAME, PASSWORD, ...)
│   └── logging_config.py       # Logging configuration settings
├── core/
│   └── mcp_server.py           # MCP wiring, GVM connection, tool registration
├── services/
│   └── gvm_client.py           # Typed wrapper around python-gvm + XML parsing
├── tools/
│   ├── vm_workflow_tools.py      # VM workflow orchestration tools
│   ├── inspection_control_tools.py # Inspection/control tools for existing scan state
│   └── utils/
│       ├── constants.py            # Tool-scoped constants (scanner/config/port list IDs, formats)
│       └── helpers.py              # Internal parsing/formatting helpers for tool outputs
└── models/
    └── generated/             # Auto-generated dataclasses (xsdata output)

Requirements

• Docker Engine + Docker Compose plugin
• A Greenbone/OpenVAS instance with a reachable gvmd Unix socket
• Valid GMP credentials

Installation

Compatibility

This server has been tested only with Greenbone/OpenVAS deployed via containers, particularly Greenbone Community Edition with the official container setup: https://greenbone.github.io/docs/latest/22.4/container/

Prerequisites

Ensure the official Greenbone Community Edition container setup is running by executing the following command in the directory where you have the docker-compose.yml for Greenbone:

docker compose -f <path-to-greenbone-compose>/docker-compose.yml up -d

Note: The official Greenbone compose setup uses the gvmd_socket_vol volume mounted at /run/gvmd in the containers. With the default compose configuration, this named volume is usually available as:

greenbone-community-edition_gvmd_socket_vol.

In this project the same named volume is used to access the gvmd socket from the MCP server container.

1) Clone this repository

git clone https://github.com/matteocolazilli/GreenboneMCP.git
cd GreenboneMCP

2) Build this MCP image

docker build -t greenbonemcp:latest .

3) Create .env configuration and set configuration values

cp .env.example .env

Edit .env with your credentials and desired settings.

You can use this .env by passing it at runtime with --env-file to the docker run command.

The server reads configuration from the following environment variables, which if not set it falls back to defaults:

• USERNAME: GMP username (default: admin)
• PASSWORD: GMP password (required: no default, must be set)
• LOG_LEVEL: application log level (default: INFO)

4) Configure the MCP client and run the server

Configure your MCP client/agent, accord

... View full README on GitHub