{
  "markdown": "# Nexus MCP Server\n\n<!-- mcp-name: io.github.addozhang/nexus -->\n\nEnglish | [简体中文](README.zh-CN.md)\n\nMCP (Model Context Protocol) server for Sonatype Nexus Repository Manager 3 (OSS and Pro), enabling AI assistants to query Maven, Python (PyPI), and Docker repositories.\n\n## Features\n- **Multiple transport modes** - SSE (default) or streamable-http transport\n- **HTTP streaming transport** - Modern SSE-based transport with header authentication\n- **Per-request authentication** - Credentials passed via HTTP headers (no hardcoded secrets)\n- **Maven support** - Search artifacts, list versions, get metadata\n- **Python support** - Search packages, list versions, get metadata\n- **Docker support** - List images, get tags, image metadata\n- **FastMCP framework** - Fast, modern Python implementation\n\n## Compatibility\n\n**Supported Nexus versions:**\n- ✅ Nexus Repository Manager 3.x OSS (Open Source)\n- ✅ Nexus Repository Manager 3.x Pro\n\nThis server uses the standard Nexus REST API v1 (`/service/rest/v1`), which is available in both OSS and Pro editions.\n\n## Available Tools\n\nThis MCP server provides **6 read-only tools** for querying Nexus repositories:\n\n### 📦 Maven Tools\n| Tool | Description | Parameters |\n|------|-------------|------------|\n| `search_maven_artifact` | Search for Maven artifacts | `group_id`, `artifact_id`, `version`, `repository` |\n| `get_maven_versions` | Get all versions of a Maven artifact (paginated) | `group_id`, `artifact_id`, `repository`, `page_size`, `continuation_token` |\n\n### 🐍 Python/PyPI Tools\n| Tool | Description | Parameters |\n|------|-------------|------------|\n| `search_python_package` | Search for Python packages | `name`, `repository` |\n| `get_python_versions` | Get all versions of a Python package (paginated) | `package_name`, `repository`, `page_size`, `continuation_token` |\n\n### 🐳 Docker Tools\n| Tool | Description | Parameters |\n|------|-------------|------------|\n| `list_docker_images` | List all Docker images in a repository | `repository` |\n| `get_docker_tags` | Get all tags for a Docker image | `repository`, `image_name` |\n\n**Note:** All tools are read-only and safe to use. No write operations (create/update/delete) are supported.\n\n## Installation\n\n### From Source\n```bash\n# Clone the repository\ngit clone https://github.com/your-org/nexus-mcp-server.git\ncd nexus-mcp-server\n\n# Create virtual environment\npython -m venv venv\nsource venv/bin/activate  # or venv/bin/activate.fish\n\n# Install in development mode\npip install -e \".[dev]\"\n\n# Run the server (defaults to http://0.0.0.0:8000)\npython -m nexus_mcp\n```\n\n### Using Docker\n```bash\n# Quick start\ndocker run -p 8000:8000 addozhang/nexus-mcp-server:latest\n\n# Or use docker-compose\ndocker-compose up\n\n# See DOCKER.md for detailed deployment guide\n```\n\nFor detailed deployment guide, see [DOCKER.md](DOCKER.md).\n\n## Configuration\n\n### Server Configuration\nThe server can be configured using command line arguments or environment variables:\n\n| Variable | CLI Argument | Description | Default |\n|----------|--------------|-------------|---------|\n| `NEXUS_MCP_HOST` | `--host` | Host to bind to | `0.0.0.0` |\n| `NEXUS_MCP_PORT` | `--port` | Port to listen on | `8000` |\n| `NEXUS_MCP_TRANSPORT` | `--transport` | Transport mode (`sse` or `streamable-http`) | `sse` |\n\n**Priority:** CLI arguments > Environment variables > Default values\n\n**Transport Modes:**\n- `sse` (default) - Server-Sent Events transport, compatible with most MCP clients\n- `streamable-http` - Streamable HTTP transport for clients that prefer this protocol\n\n### Running the Server\n\n#### Local Development\n```bash\n# SSE mode (default)\npython -m nexus_mcp\n\n# Streamable-HTTP mode\npython -m nexus_mcp --transport streamable-http\n\n# Custom port\npython -m nexus_mcp --port 9000\n\n# Custom host and port\npython -m nexus_mcp --host 127.0.0.1 --port 9000\n```\n\n#### Using Docker\n```bash\n# SSE mode (default)\ndocker run -p 8000:8000 addozhang/nexus-mcp-server:latest\n\n# Streamable-HTTP mode\ndocker run -e NEXUS_MCP_TRANSPORT=streamable-http -p 8000:8000 addozhang/nexus-mcp-server:latest\n\n# Custom port\ndocker run -e NEXUS_MCP_PORT=9000 -p 9000:9000 addozhang/nexus-mcp-server:latest\n\n# Or use docker-compose\ndocker-compose up\n\n# See DOCKER.md for detailed deployment guide\n```\n\nFor detailed deployment guide, see [DOCKER.md](DOCKER.md).\n\n### Authentication via HTTP Headers\nCredentials are passed as HTTP headers with each request:\n\n| Header | Description | Example | Required |\n|--------|-------------|---------|----------|\n| `X-Nexus-Url` | Nexus instance URL | `https://nexus.company.com` | Yes |\n| `X-Nexus-Username` | Username | `admin` | Yes |\n| `X-Nexus-Password` | Password | `secret123` | Yes |\n| `X-Nexus-Verify-SSL` | Verify SSL certificates | `false` | No (default: `true`) |\n\n**Note**: Set `X-Nexus-Verify-SSL: false` when connecting to self-hosted Nexus instances with self-signed certificates.\n\n### MCP Client Configuration (Claude Desktop)\nAdd to your Claude Desktop configuration (`~/.config/claude/claude_desktop_config.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"nexus\": {\n      \"url\": \"http://localhost:8000/mcp\",\n      \"headers\": {\n        \"X-Nexus-Url\": \"https://nexus.company.com\",\n        \"X-Nexus-Username\": \"admin\",\n        \"X-Nexus-Password\": \"secret123\"\n      }\n    }\n  }\n}\n```\n\nFor self-signed certificates:\n```json\n{\n  \"mcpServers\": {\n    \"nexus\": {\n      \"url\": \"http://localhost:8000/mcp\",\n      \"headers\": {\n        \"X-Nexus-Url\": \"https://nexus.company.com\",\n        \"X-Nexus-Username\": \"admin\",\n        \"X-Nexus-Password\": \"secret123\",\n        \"X-Nexus-Verify-SSL\": \"false\"\n      }\n    }\n  }\n}\n```\n\n### MCP Client Configuration (Other Clients)\nFor other MCP clients that support HTTP transport:\n\n```json\n{\n  \"url\": \"http://localhost:8000/mcp\",\n  \"headers\": {\n    \"X-Nexus-Url\": \"https://nexus.company.com\",\n    \"X-Nexus-Username\": \"your-username\",\n    \"X-Nexus-Password\": \"your-password\"\n  }\n}\n```\n\n## MCP Tools\n\n### Maven Tools\n| Tool | Description | Parameters |\n|------|-------------|------------|\n| `search_maven_artifact` | Search Maven repositories | `group_id`, `artifact_id`, `version`, `repository` |\n| `get_maven_versions` | Get versions of an artifact (paginated) | `group_id`, `artifact_id`, `repository`, `page_size` (default 50), `continuation_token` |\n\n**Pagination example:**\n```python\n# First page\nresponse = get_maven_versions(\"com.example\", \"myapp\")\n# response contains: versions, hasMore, continuationToken (if hasMore is true)\n\n# Next page\nif response[\"hasMore\"]:\n    next_response = get_maven_versions(\n        \"com.example\", \n        \"myapp\", \n        continuation_token=response[\"continuationToken\"]\n    )\n```\n\n### Python Tools\n| Tool | Description | Parameters |\n|------|-------------|------------|\n| `search_python_package` | Search Python packages | `name`, `repository` |\n| `get_python_versions` | Get versions of a package (paginated) | `package_name`, `repository`, `page_size` (default 50), `continuation_token` |\n\n**Pagination:** Same pattern as Maven - check `hasMore` and use `continuationToken` for subsequent pages.\n\n### Docker Tools\n| Tool | Description | Parameters |\n|------|-------------|------------|\n| `list_docker_images` | List images in a repository | `repository` |\n| `get_docker_tags` | Get tags for an image | `repository`, `image_name` |\n\n## Development\n\n### Running Tests\n```bash\npytest tests/ -v\n```\n\n### Type Checking\n```bash\nmypy src/\n```\n\n### Linting\n```bash\nruff check src/ tests/\n```\n\n## Project Structure\n```\nnexus-mcp-server/\n├── specs/                    # Requirements documents\n│   ├── authentication.md\n│   ├── maven-support.md\n│   ├── python-support.md\n│   ├── docker-support.md\n│   ├── mcp-architecture.md\n│   └── http-streaming.md\n├── src/nexus_mcp/           # Source code\n│   ├── __init__.py          # Package init with version\n│   ├── __main__.py          # CLI entry point\n│   ├── server.py            # FastMCP server with tools\n│   ├── nexus_client.py      # Nexus REST API client\n│   ├── auth.py              # Authentication types\n│   ├── dependencies.py      # Credential extraction from headers\n│   └── tools/               # Tool implementations\n│       ├── __init__.py\n│       └── implementations.py\n├── tests/                   # Test suite\n│   ├── conftest.py          # Fixtures and sample data\n│   ├── test_nexus_client.py # Client unit tests\n│   ├── test_tools.py        # Tool integration tests\n│   └── test_http_transport.py # HTTP transport tests\n├── AGENTS.md                # Operational guide\n├── IMPLEMENTATION_PLAN.md   # Task tracking\n└── pyproject.toml           # Python project metadata\n```\n\n## Troubleshooting\n\n### Connection Errors\n- Verify the MCP server is running (`python -m nexus_mcp`)\n- Check that port 8000 is accessible\n- Verify `X-Nexus-Url` header is correct and accessible\n- Check network connectivity to your Nexus instance\n- Ensure HTTPS certificates are valid (or use HTTP for local instances)\n\n### Authentication Errors\n- Verify `X-Nexus-Username` and `X-Nexus-Password` headers are correct\n- Ensure the user has read permissions on the repositories\n- Check if the Nexus instance requires specific authentication methods\n\n### Missing Credentials Error\n- Ensure all three headers are set: `X-Nexus-Url`, `X-Nexus-Username`, `X-Nexus-Password`\n- Check that your MCP client supports HTTP headers\n\n### Empty Results\n- Verify the repository name is correct\n- Check that the package/artifact exists in Nexus\n- For Python packages, try both hyphen and underscore naming\n\n### Transport Mode Issues\n**Connection timeout with streamable-http:**\n- Ensure your client supports streamable-http transport\n- Try using SSE mode instead: `python -m nexus_mcp --transport sse`\n- Check firewall rules allow HTTP connections\n\n**Tools not appearing:**\n- Both SSE and streamable-http expose the same tools\n- Verify headers are correctly passed (X-Nexus-*)\n- Check server logs for authentication errors\n\n## License\nMIT\n\n## Contributing\nContributions welcome! Please run tests and linting before submitting PRs.\n",
  "bytes": 10012,
  "sha": "cb95199d4f52f71b8ca4c5501259cd6ca68f57bef9e16923597fff8124e7d765",
  "repo_slug": "addozhang/nexus-mcp-server",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_addozhang_nexus_4fad9164/readme"
}