nexus

Nexus MCP Server

English | 简体中文

适用于 Sonatype Nexus Repository Manager 3（OSS 和 Pro）的 MCP（Model Context Protocol）服务，可让 AI 助手查询 Maven、Python（PyPI）和 Docker 仓库。

功能

• 多种传输模式 - SSE（默认）或 streamable-http 传输
• HTTP 流式传输 - 基于现代 SSE 的传输，支持通过请求头进行身份验证
• 按请求进行身份验证 - 通过 HTTP 请求头传递凭据（无需硬编码机密信息）
• Maven 支持 - 搜索构件、列出版本、获取元数据
• Python 支持 - 搜索包、列出版本、获取元数据
• Docker 支持 - 列出镜像、获取标签、获取镜像元数据
• FastMCP 框架 - 快速、现代的 Python 实现

兼容性

支持的 Nexus 版本：

• ✅ Nexus Repository Manager 3.x OSS（开源）
• ✅ Nexus Repository Manager 3.x Pro

此服务使用标准的 Nexus REST API v1（/service/rest/v1），该 API 在 OSS 和 Pro 版本中均可用。

可用工具

此 MCP 服务提供 6 个只读工具，用于查询 Nexus 仓库：

📦 Maven 工具

工具	描述	参数
search_maven_artifact	搜索 Maven 构件	group_id、artifact_id、version、repository
get_maven_versions	获取 Maven 构件的所有版本（分页）	group_id、artifact_id、repository、page_size、continuation_token

🐍 Python/PyPI 工具

工具	描述	参数
search_python_package	搜索 Python 包	name、repository
get_python_versions	获取 Python 包的所有版本（分页）	package_name、repository、page_size、continuation_token

🐳 Docker 工具

工具	描述	参数
list_docker_images	列出仓库中的所有 Docker 镜像	repository
get_docker_tags	获取 Docker 镜像的所有标签	repository、image_name

注意： 所有工具均为只读且可安全使用。不支持写入操作（创建/更新/删除）。

安装

从源代码安装

# 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

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

详细的部署指南请参阅 DOCKER.md。

配置

服务配置

可以使用命令行参数或环境变量配置服务：

变量	CLI 参数	描述	默认值
NEXUS_MCP_HOST	--host	绑定的主机	0.0.0.0
NEXUS_MCP_PORT	--port	监听端口	8000
NEXUS_MCP_TRANSPORT	--transport	传输模式（sse 或 streamable-http）	sse

优先级： CLI 参数 > 环境变量 > 默认值

传输模式：

• sse（默认）- Server-Sent Events 传输，兼容大多数 MCP 客户端
• streamable-http - 适用于偏好此协议的客户端的 Streamable HTTP 传输

运行服务

本地开发

# 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

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

详细的部署指南请参阅 DOCKER.md。

通过 HTTP 请求头进行身份验证

每个请求都会通过 HTTP 请求头传递凭据：

请求头	描述	示例	必填
X-Nexus-Url	Nexus 实例 URL	https://nexus.company.com	是
X-Nexus-Username	用户名	admin	是
X-Nexus-Password	密码	secret123	是
X-Nexus-Verify-SSL	验证 SSL 证书	false	否（默认：true）

注意：连接到使用自签名证书的可自托管 Nexus 实例时，请设置 X-Nexus-Verify-SSL: false。

MCP 客户端配置（Claude Desktop）

将以下内容添加到 Claude Desktop 配置文件（~/.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"
      }
    }
  }
}

对于自签名证书：

{
  "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 客户端配置（其他客户端）

对于支持 HTTP 传输的其他 MCP 客户端：

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

MCP 工具

Maven 工具

工具	描述	参数
search_maven_artifact	搜索 Maven 仓库	group_id、artifact_id、version、repository
get_maven_versions	获取某个构件的版本（分页）	group_id、artifact_id、repository、page_size（默认值为 50）、continuation_token

分页示例：

# 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 工具

工具	描述	参数
search_python_package	搜索 Python 包	name、repository
get_python_versions	获取某个包的版本（分页）	package_name、repository、page_size（默认值为 50）、continuation_token

**分页：**与 Maven 的方式相同——检查 hasMore，并在后续页面中使用 continuationToken。

Docker 工具

工具	描述	参数
list_docker_images	列出仓库中的镜像	repository
get_docker_tags	获取某个镜像的标签	repository、image_name

开发

运行测试

pytest tests/ -v

类型检查

mypy src/

代码检查

ruff check src/ tests/

项目结构

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

故障排除

连接错误

• 确认 MCP 服务正在运行（python -m nexus_mcp）
• 检查端口 8000 是否可访问
• 确认 X-Nexus-Url 请求头正确且可访问
• 检查与 Nexus 实例的网络连接
• 确保 HTTPS 证书有效（或在本地实例中使用 HTTP）

身份验证错误

• 确认 X-Nexus-Username 和 X-Nexus-Password 请求头正确
• 确保用户对仓库拥有读取权限
• 检查 Nexus 实例是否要求特定的身份验证方式

缺少凭据错误

• 确保已设置全部三个请求头：X-Nexus-Url、X-Nexus-Username、X-Nexus-Password
• 检查 MCP 客户端是否支持 HTTP 请求头

结果为空

• 确认仓库名称正确
• 检查 Nexus 中是否存在该包或构件
• 对于 Python 包，尝试使用连字符和下划线两种命名方式

传输模式问题

使用 streamable-http 时连接超时：

• 确保客户端支持 streamable-http 传输
• 尝试改用 SSE 模式：python -m nexus_mcp --transport sse
• 检查防火墙规则是否允许 HTTP 连接

未显示工具：

• SSE 和 streamable-http 暴露的工具相同
• 确认请求头已正确传递（X-Nexus-*）
• 检查服务日志中是否存在身份验证错误

许可证

MIT

参与贡献

欢迎贡献！提交 PR 前，请运行测试和代码检查。