Nexus

Nexus MCP Server

English | 简体中文

MCP (Model Context Protocol) server for Sonatype Nexus Repository Manager 3 (OSS and Pro), enabling AI assistants to query Maven, Python (PyPI), and Docker repositories.

Features

• Multiple transport modes - SSE (default) or streamable-http transport
• HTTP streaming transport - Modern SSE-based transport with header authentication
• Per-request authentication - Credentials passed via HTTP headers (no hardcoded secrets)
• Maven support - Search artifacts, list versions, get metadata
• Python support - Search packages, list versions, get metadata
• Docker support - List images, get tags, image metadata
• FastMCP framework - Fast, modern Python implementation

Compatibility

Supported Nexus versions:

• ✅ Nexus Repository Manager 3.x OSS (Open Source)
• ✅ Nexus Repository Manager 3.x Pro

This server uses the standard Nexus REST API v1 (/service/rest/v1), which is available in both OSS and Pro editions.

Available Tools

This MCP server provides 6 read-only tools for querying Nexus repositories:

📦 Maven Tools

🐍 Python/PyPI Tools

🐳 Docker Tools

Note: All tools are read-only and safe to use. No write operations (create/update/delete) are supported.

Installation

From Source

# Clone the repositorygit clone https://github.com/your-org/nexus-mcp-server.gitcd nexus-mcp-server
# Create virtual environmentpython -m venv venvsource venv/bin/activate  # or venv/bin/activate.fish
# Install in development modepip install -e ".[dev]"
# Run the server (defaults to http://0.0.0.0:8000)python -m nexus_mcp

Using Docker

# Quick startdocker run -p 8000:8000 addozhang/nexus-mcp-server:latest
# Or use docker-composedocker-compose up
# See DOCKER.md for detailed deployment guide

For detailed deployment guide, see DOCKER.md.

Configuration

Server Configuration

The server can be configured using command line arguments or environment variables:

Priority: CLI arguments > Environment variables > Default values

Transport Modes:

• sse (default) - Server-Sent Events transport, compatible with most MCP clients
• streamable-http - Streamable HTTP transport for clients that prefer this protocol

Running the Server

Local Development

# SSE mode (default)python -m nexus_mcp
# Streamable-HTTP modepython -m nexus_mcp --transport streamable-http
# Custom portpython -m nexus_mcp --port 9000
# Custom host and portpython -m nexus_mcp --host 127.0.0.1 --port 9000

Using Docker

# SSE mode (default)docker run -p 8000:8000 addozhang/nexus-mcp-server:latest
# Streamable-HTTP modedocker run -e NEXUS_MCP_TRANSPORT=streamable-http -p 8000:8000 addozhang/nexus-mcp-server:latest
# Custom portdocker run -e NEXUS_MCP_PORT=9000 -p 9000:9000 addozhang/nexus-mcp-server:latest
# Or use docker-composedocker-compose up
# See DOCKER.md for detailed deployment guide

For detailed deployment guide, see DOCKER.md.

Authentication via HTTP Headers

Credentials are passed as HTTP headers with each request:

Note: Set X-Nexus-Verify-SSL: false when connecting to self-hosted Nexus instances with self-signed certificates.

MCP Client Configuration (Claude Desktop)

Add to your Claude Desktop configuration (~/.config/claude/claude_desktop_config.json):

{  "mcpServers": {    "nexus": {      "url": "http://localhost:8000/mcp",      "headers": {        "X-Nexus-Url": "https://nexus.company.com",        "X-Nexus-Username": "admin",        "X-Nexus-Password": "secret123"      }    }  }}

For self-signed certificates:

{  "mcpServers": {    "nexus": {      "url": "http://localhost:8000/mcp",      "headers": {        "X-Nexus-Url": "https://nexus.company.com",        "X-Nexus-Username": "admin",        "X-Nexus-Password": "secret123",        "X-Nexus-Verify-SSL": "false"      }    }  }}

MCP Client Configuration (Other Clients)

For other MCP clients that support HTTP transport:

{  "url": "http://localhost:8000/mcp",  "headers": {    "X-Nexus-Url": "https://nexus.company.com",    "X-Nexus-Username": "your-username",    "X-Nexus-Password": "your-password"  }}

MCP Tools

Maven Tools

Pagination example:

# First pageresponse = get_maven_versions("com.example", "myapp")# response contains: versions, hasMore, continuationToken (if hasMore is true)
# Next pageif response["hasMore"]:    next_response = get_maven_versions(        "com.example",         "myapp",         continuation_token=response["continuationToken"]    )

Python Tools

Pagination: Same pattern as Maven - check hasMore and use continuationToken for subsequent pages.

Docker Tools

Development

Running Tests

pytest tests/ -v

Type Checking

mypy src/

Linting

ruff check src/ tests/

Project Structure

nexus-mcp-server/├── specs/                    # Requirements documents│   ├── authentication.md│   ├── maven-support.md│   ├── python-support.md│   ├── docker-support.md│   ├── mcp-architecture.md│   └── http-streaming.md├── src/nexus_mcp/           # Source code│   ├── __init__.py          # Package init with version│   ├── __main__.py          # CLI entry point│   ├── server.py            # FastMCP server with tools│   ├── nexus_client.py      # Nexus REST API client│   ├── auth.py              # Authentication types│   ├── dependencies.py      # Credential extraction from headers│   └── tools/               # Tool implementations│       ├── __init__.py│       └── implementations.py├── tests/                   # Test suite│   ├── conftest.py          # Fixtures and sample data│   ├── test_nexus_client.py # Client unit tests│   ├── test_tools.py        # Tool integration tests│   └── test_http_transport.py # HTTP transport tests├── AGENTS.md                # Operational guide├── IMPLEMENTATION_PLAN.md   # Task tracking└── pyproject.toml           # Python project metadata

Troubleshooting

Connection Errors

• Verify the MCP server is running (python -m nexus_mcp)
• Check that port 8000 is accessible
• Verify X-Nexus-Url header is correct and accessible
• Check network connectivity to your Nexus instance
• Ensure HTTPS certificates are valid (or use HTTP for local instances)

Authentication Errors

• Verify X-Nexus-Username and X-Nexus-Password headers are correct
• Ensure the user has read permissions on the repositories
• Check if the Nexus instance requires specific authentication methods

Missing Credentials Error

• Ensure all three headers are set: X-Nexus-Url, X-Nexus-Username, X-Nexus-Password
• Check that your MCP client supports HTTP headers

Empty Results

• Verify the repository name is correct
• Check that the package/artifact exists in Nexus
• For Python packages, try both hyphen and underscore naming

Transport Mode Issues

Connection timeout with streamable-http:

• Ensure your client supports streamable-http transport
• Try using SSE mode instead: python -m nexus_mcp --transport sse
• Check firewall rules allow HTTP connections

Tools not appearing:

• Both SSE and streamable-http expose the same tools
• Verify headers are correctly passed (X-Nexus-*)
• Check server logs for authentication errors

License

MIT

Contributing

Contributions welcome! Please run tests and linting before submitting PRs.