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, according to its documentation, to run the GreenboneMCP server with the following docker run command:

docker run 
  --rm -i 
  --env-file <path-to-your-env-file> 
  --name greenbonemcp 
  --volume greenbone-community-edition_gvmd_socket_vol:/run/gvmd 
  greenbonemcp:latest 

Note: the --env-file path must point to the .env you created in step 3.

5) Enjoy!

Use your MCP-compatible assistant to interact with OpenVAS through the tools exposed by this server!

Contributing

• Open an Issue for bugs, ideas, or feature requests.
• Open a Pull Request with focused changes and a clear description.

Community contributions are welcome and encouraged.

Tool Module Conventions

To keep tool modules maintainable:

• keep MCP tool handlers in src/tools/*_tools.py
• keep non-tool helper functions (parsing, formatting, output shaping) under src/tools/utils/ (for example src/tools/utils/helpers.py)
• use src/services/gvm_client.py for GMP interaction primitives and keep orchestration logic in tool handlers

Developing New Tools

If you want to add new MCP tools (for example by wrapping additional python-gvm methods), you will likely need new typed models for XML responses.

This project contains models under src/models/generated.

Adding new dataclasses (current approach)

For now, when you need new dataclasses for additional GMP responses, add them manually.

Recommended workflow:

1. Collect representative XML responses for the GMP methods you want to support.
2. Use the existing models in src/models/generated as reference for naming, typing, and structure.
3. Create/update dataclasses manually to match the XML shape you need.

gvm-tools / gvm-pyshell are practical ways to obtain real XML response samples from your Greenbone instance.

License

This project is licensed under GNU GPL v3.0 or later.

See LICENSE.md for the full license text.

Third-Party Notices

This project includes and depends on third-party open-source software. See THIRD_PARTY_NOTICES.md for details on direct dependencies and their licenses.