Sonatype Nexus

Sonatype Nexus MCP Server

A Model Context Protocol server that lets AI assistants inspect, audit and document a Sonatype Nexus Repository Manager 3.x instance. It is read-only by default; administrative tools are not even listed unless you enable them.

flowchart LR
    AI[MCP client] <-->|stdio / Streamable HTTP| Server[nexus-mcp-server]
    Server <-->|REST API| Nexus[Nexus Repository 3.x]

Features

• Inventory of repositories, blob stores, tasks, cleanup policies, routing rules, content selectors, users, roles and privileges, as far as the configured account can see them.
• A relationship graph (repository → blob store, group → members, repository → cleanup policy, role → privilege) behind architecture explanations, risk checks and generated Markdown documentation.
• Bounded full-content audit of one repository, with completion evidence.
• Drift check of repositories against a declared state.
• OpenAPI discovery of the instance's REST operations.
• Every tool declares readOnlyHint, destructiveHint, idempotentHint and openWorldHint; outputs and logs redact the configured password and secret-looking keys.
• Starts without configuration, so clients and registries can list its tools; calls then report what is missing.

Used in production in read-only mode on Nexus Pro 3.96.1-01; partially verified on OSS 3.70. See docs/COMPATIBILITY.md.

Quick start

The server is listed in the MCP Registry as io.github.oomchiller/nexus-mcp-server; registry-aware clients can install it from there. Manual setup:

Container

docker run --rm -i \
  -e NEXUS_URL=https://nexus.example.com \
  -e NEXUS_USERNAME=readonly-user \
  -e NEXUS_PASSWORD \
  ghcr.io/oomchiller/nexus-mcp-server:0.2.1

Images are published for linux/amd64 and linux/arm64, run as an unprivileged user over stdio, and are configured through the environment only. Release digests are listed on the releases page.

Local process

{
  "mcpServers": {
    "nexus": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/oomchiller/[email protected]", "nexus-mcp-server"],
      "env": {
        "NEXUS_URL": "https://nexus.example.com",
        "NEXUS_USERNAME": "readonly-user",
        "NEXUS_PASSWORD": "change-me"
      }
    }
  }
}

More client examples (Claude Desktop, Codex CLI, Gemini CLI) are in examples/.

Configuration

Settings come from the environment or a .env file in the working directory.

Variable	Default	Meaning
NEXUS_URL	unset	Nexus base URL. Without it the server starts, and calls report that Nexus is not configured.
NEXUS_USERNAME / NEXUS_PASSWORD	unset	Basic authentication. Use a read-only Nexus account.
NEXUS_VERIFY_TLS	true	Verify the Nexus TLS certificate.
NEXUS_CA_BUNDLE	unset	PEM file of CA certificates to trust instead of the public roots; needs NEXUS_VERIFY_TLS=true.
NEXUS_TIMEOUT_SECONDS	30	HTTP timeout.
NEXUS_ALLOWED_HOSTS	host of NEXUS_URL	Comma-separated hosts the client may contact.
NEXUS_LOG_LEVEL	INFO	Log level (stderr).
NEXUS_MCP_MODE	readonly	readonly, audit (same gates as readonly) or admin.
NEXUS_MCP_ENABLE_WRITE_TOOLS	false	With admin, lists and allows the write tools.
NEXUS_MCP_ENABLE_RAW_API	false	Lists nexus_api_call.
NEXUS_MCP_RAW_API_GET_ONLY	false	Restrict nexus_api_call to GET.
NEXUS_MCP_MAX_RAW_RESPONSE_BYTES	1048576	Largest Nexus response accepted.
NEXUS_MCP_GRAPH_TTL_SECONDS	60	How long graph tools reuse one Knowledge Graph build; 0 rebuilds on every call.
NEXUS_MCP_ENABLE_PROMPTS	true	Register prompts.
NEXUS_MCP_ENABLE_RESOURCES	true	Register resources.

Token authentication is not implemented.

The server does not read SSL_CERT_FILE or the system trust store. For a Nexus behind a private CA, set NEXUS_CA_BUNDLE rather than disabling verification. An unreadable bundle, or a bundle with verification disabled, stops the server at startup.

Gateways that run several instances side by side and prefix only tool names (Docker MCP Gateway) should set NEXUS_MCP_ENABLE_PROMPTS=false and NEXUS_MCP_ENABLE_RESOURCES=false.

Command line

--transport {stdio,sse,streamable-http}   default stdio
--host HOST / --port PORT                 HTTP bind, default 127.0.0.1:8000, no authentication
--nexus-url URL                           overrides NEXUS_URL
--nexus-username USERNAME                 overrides NEXUS_USERNAME
--verify-ssl / --no-verify-ssl            overrides NEXUS_VERIFY_TLS
--ca-bundle PATH                          overrides NEXUS_CA_BUNDLE

Keep NEXUS_PASSWORD in the environment, not on the command line.

Tools

Group	Tools
Explanation	nexus_understand_architecture, nexus_explain_repository, nexus_explain_storage_strategy
Inventory and documentation	nexus_generate_inventory_json, nexus_generate_architecture_md, nexus_generate_repository_catalog_md, nexus_audit_repository_content
Audit	nexus_detect_architecture_smells, nexus_generate_audit_report
Drift	nexus_compare_live_state_with_declared_state
OpenAPI	nexus_openapi_list_operations, nexus_generate_capability_map

Listed only when enabled:

Tool	Requires
nexus_api_call	NEXUS_MCP_ENABLE_RAW_API=true; paths are canonicalized and restricted to /service/rest/.
nexus_delete_repository, nexus_run_task	NEXUS_MCP_MODE=admin and NEXUS_MCP_ENABLE_WRITE_TOOLS=true.

Resources: nexus://instance/summary, nexus://repositories, nexus://blobstores, nexus://tasks, nexus://cleanup-policies, nexus://security/summary, nexus://architecture, nexus://knowledge_graph. Prompts: nexus_audit_prompt, nexus_iac_drift_prompt.

Limits worth knowing: drift compares repository name, format and type only; risk checks cover a small set of graph rules; findings are only as complete as the REST APIs visible to the account. Optional endpoints that are missing for version, edition or permission reasons appear as limitations, not failures.

Safety

• Read-only by default. Write tools and the raw API are not listed unless enabled, and every write is still checked against the mode at call time.
• The client contacts only NEXUS_ALLOWED_HOSTS and only paths relative to NEXUS_URL.
• Redaction is defence in depth, not a substitute for a least-privilege Nexus account. See SECURITY.md.

Development

uv sync --locked
uv run pytest
uv run ruff check . && uv run ruff format --check .
uv run mypy src tests

See CONTRIBUTING.md, ARCHITECTURE.md, DECISIONS.md and ROADMAP.md.

License

MIT; see LICENSE.