NAME¶

bugwarden - MCP server for Bugzilla with operator-controlled security guards

SYNOPSIS¶

bugwarden --bugzilla-server <BUGZILLA_SERVER> [--transport <TRANSPORT>] [--host <HOST>] [--port <PORT>] [--allowed-hosts <HOST>] [--api-key-header <API_KEY_HEADER>] [--api-key <API_KEY>] [--api-key-file <API_KEY_FILE>] [--use-auth-header] [--read-only] [--policy <POLICY>] [--audit-config <AUDIT_CONFIG>] [-h|--help] [-V|--version]

DESCRIPTION¶

MCP server for Bugzilla with operator-controlled security guards

OPTIONS¶

--bugzilla-server <BUGZILLA_SERVER>

Base URL of the Bugzilla server (e.g., 'https://bugzilla.example.com'). Environment variable BUGZILLA_SERVER is used if the argument is not provided

--transport <TRANSPORT> [default: http]

Transport for the MCP server: 'http' (default) or 'stdio'. Environment variable MCP_TRANSPORT can also be used

Possible values:

--host <HOST> [default: 127.0.0.1]

Host address for the MCP server to listen on (http transport only). Defaults to 127.0.0.1 or the MCP_HOST environment variable

--port <PORT> [default: 8000]

Port for the MCP server to listen on (http transport only). Defaults to 8000 or the MCP_PORT environment variable

--allowed-hosts <HOST>

Hostname or 'host:port' authority accepted in an inbound Host header (http transport only). Repeat the flag to allow further hosts. Command line only, no environment variable; without it Host validation stays off and any Host header is served

--api-key-header <API_KEY_HEADER> [default: ApiKey]

HTTP header for clients to send the Bugzilla API key. Defaults to 'ApiKey' or the MCP_API_KEY_HEADER environment variable. Not consulted in server-held key mode (--api-key-file over http)

--api-key <API_KEY>

Bugzilla API key. Required for --transport stdio (no HTTP headers exist there) unless --api-key-file provides it. Environment variable BUGZILLA_API_KEY can also be used. Ignored for --transport http (clients send the key per-request via the API key header; use --api-key-file for a server-held key)

--api-key-file <API_KEY_FILE>

Path to a file holding the Bugzilla API key (e.g. a container secret or systemd LoadCredential path). Mutually exclusive with --api-key. Over http this selects server-held key mode: every request is served with this key and the per-request API key header is not consulted. An empty value counts as absent, like --api-key (so `BUGZILLA_API_KEY_FILE=` is an unset, not an error)

--use-auth-header

Use 'Authorization: Bearer' header instead of the api_key query parameter (required for some Bugzilla instances)

--read-only

Disables all tools which modify the state of a bug. Environment variable MCP_READ_ONLY=true can also be used. Can only tighten the guard policy, never loosen it

--policy <POLICY>

Path to the guard policy TOML file. Environment variable BUGWARDEN_POLICY can also be used. Without it an allow-all default policy is used

--audit-config <AUDIT_CONFIG>

Path to the audit configuration TOML file (see examples/audit.toml). Environment variable BUGWARDEN_AUDIT_CONFIG can also be used. Without it no audit stream is written

-h, --help

Print help (see a summary with '-h')

-V, --version

Print version

EXIT STATUS¶

0

Clean shutdown.

1

Startup or runtime failure: an unreadable policy or audit configuration, a key misconfiguration, a Bugzilla client or transport error.

2

Command-line usage error.

ENVIRONMENT¶

Each variable is the fallback for one option; a command-line argument always wins over the environment, and the built-in default applies when neither is given.

BUGZILLA_SERVER

Fallback for --bugzilla-server.

MCP_TRANSPORT

Fallback for --transport.

MCP_HOST

Fallback for --host.

MCP_PORT

Fallback for --port.

MCP_API_KEY_HEADER

Fallback for --api-key-header.

BUGZILLA_API_KEY

Fallback for --api-key.

BUGZILLA_API_KEY_FILE

Fallback for --api-key-file.

MCP_READ_ONLY

Fallback for --read-only.

BUGWARDEN_POLICY

Fallback for --policy.

BUGWARDEN_AUDIT_CONFIG

Fallback for --audit-config.

FILES¶

/etc/bugwarden/policy.toml

Worked example guard policy as installed by distribution packages; the source tree and release archives ship it as examples/policy.toml. The server reads a policy only when one is named with --policy or BUGWARDEN_POLICY; without one the built-in allow-all default policy applies.

/etc/bugwarden/audit.toml

Worked example audit configuration; the source tree ships it as examples/audit.toml. Without --audit-config or BUGWARDEN_AUDIT_CONFIG no audit stream is written.

EXAMPLES¶

Serve a local MCP client over stdio, the server reading the Bugzilla API key from a file:

bugwarden --transport stdio \


    --bugzilla-server https://bugzilla.example.com \


    --api-key-file ~/.config/bugwarden/api-key \


    --policy /etc/bugwarden/policy.toml

Listen on HTTP (the default transport, 127.0.0.1:8000), each client presenting its own key in the API key header:

bugwarden --bugzilla-server https://bugzilla.example.com \


    --policy /etc/bugwarden/policy.toml

Listen on HTTP with a server-held key (container secret, systemd LoadCredential): every request is served with this key and the per-request key header is not consulted:

bugwarden --bugzilla-server https://bugzilla.example.com \


    --api-key-file /run/secrets/bugzilla-api-key \


    --policy /etc/bugwarden/policy.toml