Apt MCP Server

What is Apt MCP Server about?

Apt MCP Server exposes a set of Model Context Protocol (MCP) tools that allow AI agents or client applications to manage apt packages on a Linux system. It leverages the native apt and dpkg commands with password‑less sudo privileges and returns structured, human‑readable results.

How to use Apt MCP Server?

1. Clone the repository and install dependencies with npm install.
2. Build the TypeScript source using npm run build.
3. Start the server (default stdio transport) via npm run dev or npm start.
4. From a client, connect to the server using an MCP SDK (e.g., @modelcontextprotocol/sdk/client) and call tools such as installAptPackage, removeAptPackage, queryAptPackageStatus, etc.

Key features of Apt MCP Server

• Install, remove, update, and query apt packages via MCP tools.
• Assumes password‑less sudo for seamless operation.
• Input validation and robust error handling with consistent result formatting.
• Human‑readable output includes summary, stdout, stderr, and logs.
• Designed for stdio transport, ideal for local AI agent integration.

Use cases of Apt MCP Server

• Automating system provisioning or configuration through AI‑driven workflows.
• Enabling developer tools or IDE extensions to manage dependencies on a Linux host.
• Building AI assistants that can safely perform package management tasks.
• Integrating with CI/CD pipelines that require dynamic installation of apt packages.

FAQ from the Apt MCP Server

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

Q: What transport does the server use? A: Stdio by default, which works well for local AI agents and tools.

Q: Can I use this server remotely? A: It can be adapted to HTTP/SSE transport, but stdio is recommended for local use.

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

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