DefectDojo MCP Server

The official open-source Model Context Protocol server for DefectDojo.

It lets Claude, Cursor, VS Code and other MCP clients work with your DefectDojo instance through the DefectDojo REST API v2. Ask an assistant to find the open critical findings in a product, explain a finding, compare two imports, or (when you turn writes on) import a scan and update finding status.

• Works with open-source DefectDojo 2.x and 3.x, and with DefectDojo Pro.
• Read-only by default. Write tools only exist when you enable them.
• Text from DefectDojo is marked as untrusted, because scanner output can carry prompt injection.
• Runs locally over stdio, or as a streamable HTTP server with authentication.
• No telemetry of any kind.

Quick start

You need:

1. uv, which provides the uvx command.
2. The URL of your DefectDojo instance.
3. A DefectDojo API v2 key. In DefectDojo, open the user menu and choose API v2 Key. Use a dedicated account with only the permissions the assistant needs (see Security).

Check that it starts:

DEFECTDOJO_URL=https://defectdojo.example.com DEFECTDOJO_API_KEY=your-key uvx defectdojo-mcp-server --help

The package on PyPI is defectdojo-mcp-server. A package named defectdojo-mcp also exists on PyPI, but it is an unrelated project, not this server.

Claude Desktop

Open Settings > Developer > Edit Config and add the server to claude_desktop_config.json:

{
  "mcpServers": {
    "defectdojo": {
      "command": "uvx",
      "args": ["defectdojo-mcp-server"],
      "env": {
        "DEFECTDOJO_URL": "https://defectdojo.example.com",
        "DEFECTDOJO_API_KEY": "your-api-key"
      }
    }
  }
}

Restart Claude Desktop after saving.

Claude Code

claude mcp add defectdojo \
  --env DEFECTDOJO_URL=https://defectdojo.example.com \
  --env DEFECTDOJO_API_KEY=your-api-key \
  -- uvx defectdojo-mcp-server

Cursor

Add this to ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project):

{
  "mcpServers": {
    "defectdojo": {
      "command": "uvx",
      "args": ["defectdojo-mcp-server"],
      "env": {
        "DEFECTDOJO_URL": "https://defectdojo.example.com",
        "DEFECTDOJO_API_KEY": "your-api-key"
      }
    }
  }
}

VS Code

Add this to .vscode/mcp.json. VS Code asks for the API key once and stores it securely, so the key stays out of the file:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "defectdojo-api-key",
      "description": "DefectDojo API v2 key",
      "password": true
    }
  ],
  "servers": {
    "defectdojo": {
      "type": "stdio",
      "command": "uvx",
      "args": ["defectdojo-mcp-server"],
      "env": {
        "DEFECTDOJO_URL": "https://defectdojo.example.com",
        "DEFECTDOJO_API_KEY": "${input:defectdojo-api-key}"
      }
    }
  }
}

Docker

docker run -i --rm \
  -e DEFECTDOJO_URL=https://defectdojo.example.com \
  -e DEFECTDOJO_API_KEY=your-api-key \
  ghcr.io/defectdojo/defectdojo-mcp

To build the image yourself instead, run docker build -t defectdojo-mcp . in a clone and use defectdojo-mcp as the image name.

Use "command": "docker" with these arguments in any client config above to run it in a container. For HTTP mode inside a container, bind all interfaces in the container (--host 0.0.0.0), publish the port to loopback only (-p 127.0.0.1:8000:8000), and set DEFECTDOJO_MCP_ALLOWED_HOSTS.

Configuration

All settings come from environment variables.

Tools

Every tool returns JSON. List tools are paged with limit and offset, and each page reports count and next_offset.

Read tools (always available)

Write tools (only with DEFECTDOJO_ALLOW_WRITES=true)

Scan reports reach the server in one of two ways. Over stdio, pass file_path pointing at a file inside one of the DEFECTDOJO_IMPORT_DIRS folders. Over stdio or HTTP, pass the report as file_content_base64 with a file_name.

File path imports fail closed. With no DEFECTDOJO_IMPORT_DIRS set, the server refuses them instead of falling back to its working directory. It also refuses the home folder and the filesystem root as import folders, resolves symlinks before checking that a file is inside an allowed folder, rejects hidden files and anything inside a hidden folder (any path part that starts with a dot, before or after following symlinks), enforces the size limit, and never includes file contents in error messages. Point DEFECTDOJO_IMPORT_DIRS at a dedicated reports folder, not at a home folder or a whole repository.

Prompts

Read-only by default

Without DEFECTDOJO_ALLOW_WRITES=true the write tools are not registered at all, so an assistant cannot call them even by mistake. The prompts and server instructions also tell the assistant whether changes are possible.

To enable writes, add "DEFECTDOJO_ALLOW_WRITES": "true" to the env block of your client config. Most clients still ask you to approve each tool call, and the write tools carry MCP annotations that mark them as state-changing.

Security

Prompt injection

Finding titles, descriptions, notes, file paths, component names and similar fields usually come straight from scanner output. Anyone who controls something that gets scanned can put text there, including instructions aimed at an AI assistant.

This server wraps every free-text value from DefectDojo in a pair of tags with a random 16-character hex suffix chosen for that value, for example <untrusted-data-3f9c0a7b1e2d4c58>...</untrusted-data-3f9c0a7b1e2d4c58>. A client or model recognizes the data by the matching suffix on the opening and closing tag. Text inside cannot close the wrapper early because it cannot guess the suffix. As a second layer, look-alike tags inside the text are escaped, bidirectional control characters are shown as code points such as [U+202E], and long fields are truncated. Tool descriptions and the server instructions tell the model to treat tagged text as data only. This lowers the risk but cannot remove it, so keep a person in the loop for write actions and review what the assistant proposes.

Local files

A prompt-injected assistant could try to upload local files, such as keys or dotfiles, to DefectDojo through import_scan. That is why file path imports are off until you name the folders in DEFECTDOJO_IMPORT_DIRS, and why hidden files are always refused. Keep scan reports in their own folder.

API key scope

The server can do anything the API key's user can do. Create a dedicated DefectDojo user for the assistant, give it access only to the products it needs, and keep writes off unless you need them. The key is sent only to DEFECTDOJO_URL, redirects are never followed, and the key is redacted from logs and error messages.

HTTP mode

Over stdio the server is only reachable by the client that started it. HTTP mode is for shared or remote setups:

export DEFECTDOJO_URL=https://defectdojo.example.com
export DEFECTDOJO_API_KEY=your-api-key
export DEFECTDOJO_MCP_AUTH_TOKEN=$(python -c "import secrets; print(secrets.token_urlsafe(32))")
defectdojo-mcp --transport http --host 127.0.0.1 --port 8000

The endpoint is http://127.0.0.1:8000/mcp, and /healthz answers without authentication for health checks. The server refuses to start in HTTP mode without one of these authentication modes:

• Token mode (--http-auth token, the default). Every request must send Authorization: Bearer <DEFECTDOJO_MCP_AUTH_TOKEN>. All callers share the server's DefectDojo key, so give that key the narrowest permissions that work for everyone.
• Pass-through mode (--http-auth passthrough). Every request carries the caller's own DefectDojo key in X-DefectDojo-Api-Key or Authorization: Token <key>. The server holds no key of its own and DefectDojo enforces each caller's permissions.

The server binds to 127.0.0.1 by default and checks the Host and Origin headers to block DNS rebinding. To serve other machines, bind a non-loopback address, set DEFECTDOJO_MCP_ALLOWED_HOSTS to the public host name, and put a TLS-terminating reverse proxy in front. Keys and tokens travel in headers, so plain HTTP across a network exposes them.

Report security problems as described in SECURITY.md.

Compatibility

• Open-source DefectDojo 2.x and 3.x. The server uses long-standing API v2 endpoints and skips fields a version does not return. On older releases, filters that the instance does not know are ignored by DefectDojo, so the date filters on list_findings need a release from late 2024 or newer. list_locations uses the locations API in 3.x and falls back to endpoints on older releases.
• DefectDojo Pro. Everything here works against Pro through the same API. Pro also includes its own built-in MCP server at https://<your-instance>/mcp with more capabilities, and get_instance_info mentions it when it detects Pro.
• MCP. Built on the official MCP Python SDK 2.x and protocol version 2026-07-28, with fallback to earlier protocol versions for older clients.
• Python 3.11 or newer.

Development

git clone https://github.com/DefectDojo/defectdojo-mcp
cd defectdojo-mcp
uv sync
uv run pytest            # unit tests with mocked HTTP
uv run ruff check .
uv run ruff format --check .
uv run mypy

The live test suite runs every tool against a real DefectDojo instance over stdio. Point it at a disposable instance, since it creates products, engagements and findings:

DEFECTDOJO_LIVE_URL=http://127.0.0.1:8080 DEFECTDOJO_LIVE_API_KEY=your-key uv run pytest -m live

See CONTRIBUTING.md for more.

License

BSD 3-Clause. See LICENSE.