mcp-defectdojo

MCP server for DefectDojo vulnerability management. Exposes 24 tools for managing products, engagements, tests, findings, scan imports, and finding lifecycle through the Model Context Protocol.

Getting Started Guide — step-by-step setup, from install through connecting your first MCP client.

Quick Start

git clone https://github.com/inspicere/mcp-defectdojo.git && cd mcp-defectdojo
cp .env.example .env
# Edit .env — set DEFECTDOJO_URL and DEFECTDOJO_API_KEY
uv sync --frozen
uv run mcp-defectdojo

Requires Python 3.12+, uv, and a running DefectDojo instance.

Configuration

All configuration is via environment variables. Copy env.example to .env for local development.

Required

Variable	Description
DEFECTDOJO_URL	Base URL of the DefectDojo instance (must use https:// unless overridden)
DEFECTDOJO_API_KEY	API key for DefectDojo (generate at DefectDojo > API v2 > Your API Key)

Optional — Dual API Key Mode

For least-privilege access, use separate read/write keys instead of DEFECTDOJO_API_KEY:

Variable	Description
DEFECTDOJO_READ_API_KEY	Read-only API key (used for GET requests)
DEFECTDOJO_WRITE_API_KEY	Write API key (used for POST/PATCH requests)

Optional — MCP Authentication (RBAC)

Token-role bindings using MCP_ROLE_* env vars (preferred):

Variable	Description
MCP_ROLE_<NAME>	Format: <token>:<role>. Binds a bearer token to a role. Name becomes the caller ID.

Four roles are available, each inheriting from the one below:

Role	Permissions
admin	All permissions including product_mgmt
writer	engagement_mgmt, finding_mgmt, scan_mgmt, metadata_read, system
scanner	scan_mgmt, metadata_read, system
reader	metadata_read, system

Example: MCP_ROLE_CI=tok_abc123:scanner grants the token scanner-level access.

Legacy variables (mapped to RBAC roles for backward compatibility):

Variable	Maps to
MCP_AUTH_TOKEN	admin role
MCP_READ_TOKEN	reader role

Optional — Transport

Variable	Default	Description
FASTMCP_TRANSPORT	stdio	Transport mode: stdio, sse, streamable-http, http
FASTMCP_HOST	0.0.0.0	Bind address for network transports
FASTMCP_PORT	8000	Port for network transports

Optional — Security

Variable	Default	Description
ALLOW_INSECURE_HTTP	false	Allow http:// URLs (TLS required by default)
MUTATION_RATE_LIMIT	60	Max mutations per rate window per authenticated caller (per-token bucket)
OPEN_ACCESS_MUTATION_RATE_LIMIT	10	Max mutations per rate window across all unauthenticated traffic (one shared bucket — applies only when REQUIRE_AUTH=false)
MUTATION_RATE_WINDOW	60	Rate window in seconds (applies to both buckets)
UNTRUSTED_CONTENT_WRAPPING	on	F-002 read-side wrapping kill-switch. When on (default), title, description, tags, notes, and note entry fields are returned inside {"value": <content>, "_warning": "untrusted-content: ..."}. Set to off only for legacy downstream consumers that cannot parse the wrapped shape.

Optional — Logging & Audit

Variable	Default	Description
LOG_LEVEL	INFO	DEBUG, INFO, WARNING, ERROR, CRITICAL
AUDIT_HMAC_KEY	(ephemeral)	HMAC key for audit log integrity chain. Required for cross-restart log verification. Generate with: python3 -c "import secrets; print(secrets.token_hex(32))"
AUDIT_LOG_FILE	(stderr only)	Path for d

... View full README on GitHub