GdMacmillan/apt-mcp-server

Apt MCP Server

A TypeScript-based Model Context Protocol (MCP) server for controlling the apt package manager on Linux. Designed for integration with AI agents (e.g., Cursor, Claude Desktop, Windsurf) and developer tools, it exposes tools for installing, removing, updating, and querying apt packages using the system's native apt and dpkg binaries with sudo privileges.

Features

• Install, remove, update, and query apt packages via MCP tools
• Secure, passwordless sudo assumed for all operations
• Input validation and robust error handling
• Consistent, human-readable output for all tools
• Designed for stdio transport (default for local AI agent integration)

Setup & Installation

1. Clone the repository:

   git clone <your-repo-url>
   cd popos-control-mcp
   

2. Install dependencies:

   npm install
   

3. Build the project:

   npm run build
   

4. Run the server (stdio transport):

   npm run dev
   # or
   npm start
   

Note: The server assumes the user has passwordless sudo for apt operations.

Tools & API Endpoints

All tools are exposed via MCP and can be called by AI agents or clients. Each tool returns a plain text response with a summary, stdout, stderr, and logs (if any).

1. installAptPackage

• Description: Install one or more apt packages.
• Parameters:
  • packages: array of package names (e.g., ["curl", "git"])
• Example Input:

  { "packages": ["curl"] }
  

• Example Output:

  Result: SUCCESS
  Summary: Apt install succeeded for: curl
  [stdout]
  ...
  [stderr]
  ...
  

2. removeAptPackage

• Description: Remove one or more apt packages.
• Parameters:
  • packages: array of package names
• Example Input:

  { "packages": ["curl"] }
  

• Example Output:

  Result: SUCCESS
  Summary: Apt remove succeeded for: curl
  [stdout]
  ...
  [stderr]
  ...
  

3. queryAptPackageStatus

• Description: Query if a package is installed, available, or upgradable.
• Parameters:
  • package: package name (string)
• Example Input:

  { "package": "curl" }
  

• Example Output:

  Result: SUCCESS
  Summary: Status for package curl: Installed=installed, Upgradable=false, Available=available
  [stdout]
  Package: curl
  Installed: installed
  Upgradable: no
  Available: available
  

4. updateAptPackages

• Description: Update the apt package list and upgrade all packages.
• Parameters: none
• Example Input:

  {}
  

• Example Output:

  Result: SUCCESS
  Summary: Apt update and upgrade completed successfully.
  [stdout]
  apt update stdout:
  ...
  apt upgrade stdout:
  ...
  [stderr]
  ...
  

5. listUpgradableAptPackages

• Description: List all upgradable apt packages.
• Parameters: none
• Example Input:

  {}
  

• Example Output:

  Result: SUCCESS
  Summary: Listed upgradable packages successfully.
  [stdout]
  ...
  [stderr]
  ...
  

6. upgradeSpecificAptPackage

• Description: Upgrade a specific apt package.
• Parameters:
  • package: package name (string)
• Example Input:

  { "package": "curl" }
  

• Example Output:

  Result: SUCCESS
  Summary: Apt only-upgrade succeeded for: curl
  [stdout]
  ...
  [stderr]
  ...
  

Example Usage

CLI (stdio transport)

You can test the server using the MCP CLI or by connecting with an AI agent (e.g., Cursor, Claude Desktop).

Node.js Example

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

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

(async () => {
  await client.connect(transport);
  const result = await client.callTool("installAptPackage", { packages: ["curl"] });
  console.log(result);
})();

Error Handling & Troubleshooting

• All errors are returned in a consistent format with Result: ERROR and a summary.
• Common error causes:
  • Invalid package name: check spelling and allowed characters
  • Package not found: ensure the package exists in your repositories
  • Permission denied: ensure passwordless sudo is configured
  • Apt lock: the server retries once automatically, but if the error persists, wait and try again
• Example error output:

  Result: ERROR
  Summary: Apt install failed: E: Unable to locate package notarealpackage
  [stdout]
  ...
  [stderr]
  E: Unable to locate package notarealpackage
  

FAQ

Q: Does the server require passwordless sudo? A: Yes, all apt/dpkg commands are run with sudo and assume no password prompt.

Q: What transport does the server use? A: Stdio by default, for easy integration with local AI agents and tools.

Q: Can I use this server remotely? A: You can adapt it to use HTTP/SSE transport, but stdio is recommended for local/agent use.

Q: How do I add new tools? A: Add a new server.addTool block in src/index.ts following the existing pattern.

License

MIT