MCP Harbor
MCP Harbor is a Node.js application that provides a Model Context Protocol (MCP) server for interacting with Harbor container registry.
Table of Contents
Features
- MCP Server: Exposes tools for interacting with Harbor through the Model Context Protocol
- Harbor Operations: Supports operations for projects, repositories, tags, and Helm charts
- TypeScript: Written in TypeScript for better type safety and developer experience
- Automated Tests: Comprehensive test suite for reliable functionality
Prerequisites
Before installing MCP Harbor, ensure you have:
- Node.js 18.x or higher
- npm 8.x or higher
- Access to a Harbor registry instance
- Git (for cloning the repository)
Installation
-
Clone the repository:
git clone https://github.com/nomagicln/mcp-harbor.git -
Navigate to the project directory:
cd mcp-harbor -
Install dependencies:
npm install -
Build the project:
npm run build
Usage
Command Line Arguments
The application accepts the following command line arguments:
Options:
--url Harbor API URL [string] [required]
--username Harbor username [string] [required]
--password Harbor password [string] [required]
--debug Enable debug mode [boolean] [default: false]
--help Show help [boolean]
Environment Variables
Instead of command line arguments, you can also use environment variables. Create a .env file in the root directory:
# Harbor API Configuration
HARBOR_URL=https://harbor.example.com
HARBOR_USERNAME=admin
HARBOR_PASSWORD=Harbor12345
# Debug Mode (true/false)
DEBUG=false
MCP Tools
The MCP server exposes the following tools:
| Tool Name | Description | Parameters |
|---|---|---|
list_projects | List all projects in Harbor | None |
get_project | Get project details by ID | projectId: string |
create_project | Create a new project | project_name: string, metadata?: object |
delete_project | Delete a project | projectId: string |
list_repositories | List repositories in a project | projectId: string |
delete_repository | Delete a repository | projectId: string, repositoryName: string |
list_tags | List tags in a repository | projectId: string, repositoryName: string |
delete_tag | Delete a tag | projectId: string, repositoryName: string, tag: string |
list_charts | List Helm charts | projectId: string |
list_chart_versions | List chart versions | projectId: string, chartName: string |
delete_chart | Delete chart version | projectId: string, chartName: string, version: string |
Development
Running in Development Mode
npm run dev
Running Tests
# Run all tests
npm test
# Run tests with coverage
npm run test:coverage
Project Structure
mcp-harbor
├── src
│ ├── app.ts # Main application entry point (MCP server)
│ ├── definitions
│ │ └── tool.definitions.ts # Tool definitions for MCP
│ ├── services
│ │ └── harbor.service.ts # Harbor service implementation
│ └── types
│ └── index.ts # TypeScript type definitions
├── test
│ └── harbor.test.ts # Tests for Harbor service
├── .env.example # Example environment variables
├── .gitignore # Git ignore file
├── .eslintrc.json # ESLint configuration
├── package.json # Project dependencies
├── jest.config.js # Jest configuration
├── tsconfig.test.json # TypeScript configuration for tests
├── tsconfig.json # TypeScript configuration
├── LICENSE # Project license
└── README.md # Project documentation
Troubleshooting
Common Issues
-
Connection Failed
Error: Unable to connect to Harbor instance- Verify HARBOR_URL is correct and accessible
- Check network connectivity
- Ensure Harbor instance is running
-
Authentication Failed
Error: Invalid credentials- Verify HARBOR_USERNAME and HARBOR_PASSWORD are correct
- Check if user has required permissions
-
Build Errors
Error: TypeScript compilation failed- Run
npm installto ensure all dependencies are installed - Check TypeScript version compatibility
- Clear the
distdirectory and rebuild
- Run
Debug Mode
Enable debug mode by using the --debug flag or setting:
DEBUG=true
Support
For additional help:
- Review the application logs
License
This project is licensed under the MIT License - see the LICENSE file for details.