Skip to main content
Glama
mfernandezfunes

MCP Harbor

by mfernandezfunes
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

MCP Harbor

License: MIT TypeScript Node.js codecov

MCP Harbor is a Node.js application that provides a Model Context Protocol (MCP) server for interacting with Harbor container registry.

Table of Contents

Related MCP server: MCP Server

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

  1. Clone the repository:

    git clone https://github.com/nomagicln/mcp-harbor.git

  2. Navigate to the project directory:

    cd mcp-harbor

  3. Install dependencies:

    npm install

  4. 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 (or robot account name)     [string] [required]
  --password  Harbor password (mutually exclusive with --token)       [string]
  --token     Harbor token for robot/service accounts                [string]
  --insecure  Disable TLS/SSL certificate validation [boolean] [default: false]
  --debug     Enable debug mode                   [boolean] [default: false]
  --help      Show help                                             [boolean]

Note: You must provide either --password or --token, but not both.

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

# Authentication: use either PASSWORD or TOKEN (mutually exclusive)
# Option 1: Password-based authentication
HARBOR_PASSWORD=Harbor12345

# Option 2: Token-based authentication (for robot/service accounts)
# HARBOR_USERNAME=robot$myrobot
# HARBOR_TOKEN=your-robot-token-here

# Debug Mode (true/false)
DEBUG=false

# Disable TLS/SSL certificate validation (true/false)
# HARBOR_INSECURE=false

Token Authentication (Robot/Service Accounts)

Harbor supports robot accounts for automated access. To use token-based authentication:

  1. Create a robot account in your Harbor instance (Administration > Robot Accounts)

  2. Use the robot account name as --username (e.g., robot$myrobot)

  3. Use the generated token as --token

mcp-harbor --url https://harbor.example.com --username "robot\$myrobot" --token "your-robot-token"

MCP Client Configuration

Claude Desktop

Add the following to your Claude Desktop configuration file (claude_desktop_config.json):

Using password authentication:

{
  "mcpServers": {
    "harbor": {
      "command": "npx",
      "args": [
        "mcp-harbor",
        "--url", "https://harbor.example.com",
        "--username", "admin",
        "--password", "your-password"
      ]
    }
  }
}

Using token authentication (robot/service account):

{
  "mcpServers": {
    "harbor": {
      "command": "npx",
      "args": [
        "mcp-harbor",
        "--url", "https://harbor.example.com",
        "--username", "robot$myrobot",
        "--token", "your-robot-token"
      ]
    }
  }
}

With self-signed certificates:

{
  "mcpServers": {
    "harbor": {
      "command": "npx",
      "args": [
        "mcp-harbor",
        "--url", "https://harbor.example.com",
        "--username", "admin",
        "--password", "your-password",
        "--insecure"
      ]
    }
  }
}

Cursor / Windsurf

Add the following to your MCP configuration file (.cursor/mcp.json or .windsurf/mcp.json):

{
  "mcpServers": {
    "harbor": {
      "command": "npx",
      "args": [
        "mcp-harbor",
        "--url", "https://harbor.example.com",
        "--username", "admin",
        "--password", "your-password"
      ]
    }
  }
}

Using environment variables

You can also reference environment variables to avoid hardcoding credentials:

{
  "mcpServers": {
    "harbor": {
      "command": "npx",
      "args": ["mcp-harbor"],
      "env": {
        "HARBOR_URL": "https://harbor.example.com",
        "HARBOR_USERNAME": "admin",
        "HARBOR_PASSWORD": "your-password"
      }
    }
  }
}

SSE Transport (remote/shared server)

If you prefer running the MCP server as a standalone process with SSE transport:

npx mcp-harbor --url https://harbor.example.com --username admin --password your-password --sse --port 3000

Then configure your MCP client to connect via SSE at http://localhost:3000/sse.

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

  1. Connection Failed

    Error: Unable to connect to Harbor instance

    • Verify HARBOR_URL is correct and accessible

    • Check network connectivity

    • Ensure Harbor instance is running

  2. Authentication Failed

    Error: Invalid credentials

    • Verify HARBOR_USERNAME and HARBOR_PASSWORD are correct

    • Check if user has required permissions

  3. Build Errors

    Error: TypeScript compilation failed

    • Run npm install to ensure all dependencies are installed

    • Check TypeScript version compatibility

    • Clear the dist directory and rebuild

Debug Mode

Enable debug mode by using the --debug flag or setting:

DEBUG=true

Support

For additional help:

  1. Review the application logs

License

This project is licensed under the MIT License - see the LICENSE file for details.

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • MCP Harbor

    nomagicln
    A
    license
    Not graded
    quality
    F
    maintenance
    A Node.js application that provides a Model Context Protocol server for interacting with Harbor container registry, supporting operations for projects, repositories, tags, and Helm charts.
    6 npm
    7
    MIT

  • MCP Server

    JeongJaeSoon
    A
    license
    Not graded
    quality
    F
    maintenance
    A configurable server implementation that provides MCP (Model-Controller-Protocol) functionality, supporting both Node.js and Docker environments with automated setup and configuration options.
    205 npm
    MIT

  • Learn MCP Server

    saravmani-kmu
    F
    license
    Not graded
    quality
    D
    maintenance
    A Model Context Protocol (MCP) server designed for learning and experimentation. It provides a foundational setup for developers to build, run, and debug MCP server implementations using Node.js.
    -