io.github.addozhang/nexus

Official

by addozhang · Python

Query Sonatype Nexus Repository (OSS/Pro) for Maven, Python, and Docker artifacts

Query Sonatype Nexus Repository for Maven, Python, and Docker artifacts.

README.md10 KBView on GitHub

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

Tool	Description	Parameters
`search_maven_artifact`	Search for Maven artifacts	`group_id`, `artifact_id`, `version`, `repository`
`get_maven_versions`	Get all versions of a Maven artifact (paginated)	`group_id`, `artifact_id`, `repository`, `page_size`, `continuation_token`

🐍 Python/PyPI Tools

Tool	Description	Parameters
`search_python_package`	Search for Python packages	`name`, `repository`
`get_python_versions`	Get all versions of a Python package (paginated)	`package_name`, `repository`, `page_size`, `continuation_token`

🐳 Docker Tools

Tool	Description	Parameters
`list_docker_images`	List all Docker images in a repository	`repository`
`get_docker_tags`	Get all tags for a Docker image	`repository`, `image_name`

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

Installation

From Source

bash

# Clone the repository
git clone https://github.com/your-org/nexus-mcp-server.git
cd nexus-mcp-server

# Create virtual environment
python -m venv venv
source venv/bin/activate  # or venv/bin/activate.fish

# Install in development mode
pip install -e ".[dev]"

# Run the server (defaults to http://0.0.0.0:8000)
python -m nexus_mcp

Using Docker

bash

# Quick start
docker run -p 8000:8000 addozhang/nexus-mcp-server:latest

# Or use docker-compose
docker-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:

Variable	CLI Argument	Description	Default
`NEXUS_MCP_HOST`	`--host`	Host to bind to	`0.0.0.0`
`NEXUS_MCP_PORT`	`--port`	Port to listen on	`8000`
`NEXUS_MCP_TRANSPORT`	`--transport`	Transport mode (`sse` or `streamable-http`)	`sse`

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

bash

# SSE mode (default)
python -m nexus_mcp

# Streamable-HTTP mode
python -m nexus_mcp --transport streamable-http

# Custom port
python -m nexus_mcp --port 9000

# Custom host and port
python -m nexus_mcp --host 127.0.0.1 --port 9000

Using Docker

bash

# SSE mode (default)
docker run -p 8000:8000 addozhang/nexus-mcp-server:latest

# Streamable-HTTP mode
docker run -e NEXUS_MCP_TRANSPORT=streamable-http -p 8000:8000 addozhang/nexus-mcp-server:latest

# Custom port
docker run -e NEXUS_MCP_PORT=9000 -p 9000:9000 addozhang/nexus-mcp-server:latest

# Or use docker-compose
docker-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:

Header	Description	Example	Required
`X-Nexus-Url`	Nexus instance URL	`https://nexus.company.com`	Yes
`X-Nexus-Username`	Username	`admin`	Yes
`X-Nexus-Password`	Password	`secret123`	Yes
`X-Nexus-Verify-SSL`	Verify SSL certificates	`false`	No (default: `true`)

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):

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:

json

{
  "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:

json

{
  "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

Tool	Description	Parameters
`search_maven_artifact`	Search Maven repositories	`group_id`, `artifact_id`, `version`, `repository`
`get_maven_versions`	Get versions of an artifact (paginated)	`group_id`, `artifact_id`, `repository`, `page_size` (default 50), `continuation_token`

Pagination example:

python

# First page
response = get_maven_versions("com.example", "myapp")
# response contains: versions, hasMore, continuationToken (if hasMore is true)

# Next page
if response["hasMore"]:
    next_response = get_maven_versions(
        "com.example", 
        "myapp", 
        continuation_token=response["continuationToken"]
    )

Python Tools

Tool	Description	Parameters
`search_python_package`	Search Python packages	`name`, `repository`
`get_python_versions`	Get versions of a package (paginated)	`package_name`, `repository`, `page_size` (default 50), `continuation_token`

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

Docker Tools

Tool	Description	Parameters
`list_docker_images`	List images in a repository	`repository`
`get_docker_tags`	Get tags for an image	`repository`, `image_name`

Development

Running Tests

bash

pytest tests/ -v

Type Checking

bash

mypy src/

Linting

bash

ruff check src/ tests/

Project Structure

code

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.

Install

Configuration

Environment variables

NEXUS_BASE_URLrequired

Base URL of your Nexus Repository Manager instance (e.g., https://nexus.example.com)

NEXUS_USERNAME

Nexus username for authentication

NEXUS_PASSWORDsecret

Nexus password or token for authentication

claude_desktop_config.json

{
  "mcpServers": {
    "nexus": {
      "command": "uvx",
      "args": [
        "nexus-mcp-server"
      ],
      "env": {
        "NEXUS_BASE_URL": "<YOUR_NEXUS_BASE_URL>",
        "NEXUS_USERNAME": "<YOUR_NEXUS_USERNAME>",
        "NEXUS_PASSWORD": "<YOUR_NEXUS_PASSWORD>"
      }
    }
  }
}