Overview

APT MCP Server is a TypeScript implementation of a Model Context Protocol (MCP) server that exposes apt and dpkg operations as callable tools for AI agents and developer tooling. It wraps system apt/dpkg commands (invoked with sudo) so agents can install, remove, query, and upgrade packages on Debian-based Linux distributions using a standardized MCP interface and stdio transport.

This server is useful when integrating local AI assistants or automation pipelines that need to manage system packages programmatically — for example, an agent that provisions developer environments, diagnoses missing dependencies, or performs automated updates. It focuses on safe I/O, input validation, clear human-readable responses, and predictable error reporting for agent consumption.

Features

TypeScript MCP server exposing apt/dpkg actions as MCP tools
Tools for install, remove, query status, list upgradable, update/upgrade, and package-specific upgrades
Uses the system apt and dpkg binaries via sudo (assumes passwordless sudo)
Designed for stdio transport (default for local AI agents)
Structured, consistent plain-text responses including summary, stdout, stderr, and logs
Input validation and consistent error handling with retry for common apt locks

Installation / Configuration

Clone, install, build, and run the server locally. The examples assume Node.js/npm is installed.

# Clone the repo
git clone https://github.com/GdMacmillan/apt-mcp-server.git
cd apt-mcp-server

# Install dependencies
npm install

# Build TypeScript
npm run build

# Run in dev mode (stdio)
npm run dev

# Or run production start
npm start

Notes:

The server invokes sudo apt and sudo dpkg. Configure passwordless sudo for the account running the server or run it under an account that won’t prompt for a password.
Default transport is stdio for simple local agent integration. You can adapt the code to other MCP transports if required.

Available Tools

The server exposes a set of MCP tools. Each tool returns plain text with a Result (SUCCESS/ERROR), a one-line Summary, and captured stdout/stderr output.

Tool name	Purpose	Parameters
`installAptPackage`	Install one or more packages	`{ packages: string[] }`
`removeAptPackage`	Remove one or more packages	`{ packages: string[] }`
`queryAptPackageStatus`	Report install/availability/upgradable status for a package	`{ package: string }`
`updateAptPackages`	Run `apt update` then `apt upgrade`	`{}`
`listUpgradableAptPackages`	List all packages with available upgrades	`{}`
`upgradeSpecificAptPackage`	Upgrade a single package only	`{ package: string }`

Example tool call payload (JSON):

{ "packages": ["curl", "git"] }

Example response format:

Result: SUCCESS
Summary: Installed packages: curl, git
[stdout]
...
[stderr]
...

Use Cases

Automated onboarding: An AI assistant prepares a development VM by installing language runtimes and CLI tools it detects are missing (e.g., git, nodejs, build-essential).
Dependency healing: An agent diagnosing a failing CI job can query package status and reinstall corrupted packages.
Maintenance automation: Periodic agent-run updates that call updateAptPackages and produce logs for auditing.
Interactive troubleshooting: Human+agent workflows where the agent suggests and executes apt operations after developer approval.

Concrete example: Node.js client using MCP SDK over stdio

const { Client } = require("@modelcontextprotocol/sdk/client");
const { StdioClientTransport } = require("@modelcontextprotocol/sdk/client/stdio");

const client = new Client({ name: "mcp-test", version: "1.0.0" });
const transport = new StdioClientTransport();

(async () => {
  await client.connect(transport);
  const res = await client.callTool("queryAptPackageStatus", { package: "curl" });
  console.log(res); // structured response with Summary, stdout, stderr
})();

Output, Errors & Troubleshooting

Responses use a consistent textual schema (Result, Summary, stdout, stderr). On errors the Result is ERROR and the Summary provides a concise cause. Common issues:

Permission denied: Ensure passwordless sudo or run with an account that won’t prompt.
Package not found: Confirm package name and repositories; run updateAptPackages before installs.
Apt lock: Server retries once for lock contention; if persistent wait and retry later.

If you extend the server, follow the existing tool registration pattern (add a server.addTool in the TypeScript entrypoint) and validate inputs to keep responses predictable.

Security & Notes

This server executes system package commands — run it only in trusted environments.
Prefer stdio transport for local agent integrations. If exposing remotely, secure the transport (TLS, authentication, authorization) and limit who can invoke package operations.
License: MIT (see repository for details).

APT MCP Server: TypeScript APT Package Management