Aptly MCP Server

A Model Context Protocol (MCP) server for managing Debian package repositories using the Aptly package repository management tool.

Overview

This MCP server provides AI assistants with direct access to Aptly functionality through standardized tools and resources. It enables natural language interaction with Debian package repositories, including creation, management, and publishing operations.

Features

MCP Tools

• aptly_create_repo: Create new local repositories
• aptly_list_repos: List all repositories with filtering options
• aptly_add_packages: Add packages to repositories from uploaded files
• aptly_search_packages: Search packages across repositories
• aptly_create_snapshot: Create snapshots from repositories or other snapshots
• aptly_publish_repo: Publish repositories/snapshots for apt consumption
• aptly_create_mirror: Create mirrors of remote repositories
• aptly_upload_files: Upload package files to the server
• aptly_list_mirrors: List all configured mirrors
• aptly_update_mirror: Update mirrors with latest packages
• aptly_delete_repo: Delete repositories with safety checks

MCP Resources

• repositories: Dynamic listing of all repositories with metadata
• packages: Searchable package databases across repositories
• mirrors: Remote mirror status and configuration
• publications: Published repository information and endpoints
• snapshots: Available snapshots with creation dates and descriptions

Installation

cd aptly-mcp
npm install
npm run build

Configuration

Environment Variables

export APTLY_API_URL=http://localhost:8080  # Default Aptly API endpoint
export APTLY_AUTH_TOKEN=your_token_here     # Optional authentication token

Claude Desktop Configuration

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "aptly": {
      "command": "node",
      "args": ["/path/to/aptly-mcp/build/index.js"],
      "env": {
        "APTLY_API_URL": "http://localhost:8080"
      }
    }
  }
}

Remote Aptly Server

For remote Aptly servers with authentication:

{
  "mcpServers": {
    "aptly": {
      "command": "node",
      "args": ["/path/to/aptly-mcp/build/index.js"],
      "env": {
        "APTLY_API_URL": "https://aptly.example.com",
        "APTLY_AUTH_TOKEN": "your-auth-token"
      }
    }
  }
}

Usage Examples

Once configured with Claude Desktop, you can use natural language commands:

Repository Management

• "Create a new repository called 'production-packages' for production releases"
• "List all repositories and show their package counts"
• "Delete the 'test-repo' repository"

Package Operations

• "Add all .deb files from the 'uploads' directory to the 'main' repository"
• "Search for packages containing 'nginx' across all repositories"
• "Remove the 'old-package' from the 'main' repository"

Snapshot Management

• "Create a snapshot of the 'main' repository called 'v1.0-release'"
• "List all snapshots and their creation dates"
• "Create a merged snapshot from 'main' and 'contrib' repositories"

Publishing

• "Publish the 'main' repository to the 'stable' distribution"
• "Update the published 'testing' repository with the latest snapshot"
• "List all published repositories and their endpoints"

Mirror Management

• "Create a mirror of the Ubuntu main repository"
• "Update all mirrors to get the latest packages"
• "Show the status of the 'ubuntu-main' mirror"

Development

Building

npm run build

Testing

npm run inspector  # Launch MCP inspector for testing

Watching for Changes

npm run watch

API Documentation

The server connects to Aptly's REST API. Ensure your Aptly instance is running with API enabled:

aptly api serve -listen=":8080"

Security Considerations

• Use Unix domain sockets instead of network ports in production
• Implement proper authentication for remote Aptly servers
• Consider using a reverse proxy with HTTPS for production deployments
• Validate all inputs to prevent injection attacks

License

MIT License