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

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

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

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

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

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.