linux-mcp-server

What is linux-mcp-server?

A Model Context Protocol (MCP) server built with Spring Boot and Spring AI that executes shell commands on local or remote Linux hosts. It exposes an executeShell tool via the MCP standard interface, allowing AI assistants like Claude Desktop to perform command-line operations securely.

How to use linux-mcp-server?

1. Ensure Java 17+ and Maven 3.6+ are installed.
2. Clone the repository and edit src/main/resources/hosts.json to configure remote host credentials (IP, username, password).
3. Start the server with mvn spring-boot:run or package it as a JAR (mvn clean package; java -jar target/linux-mcp-server-1.0.0.jar). The server listens on port 3001 at /mcp.
4. Add the server to an MCP client (e.g., Claude Desktop) using its HTTP endpoint. The client will discover the executeShell tool, which accepts machineIp (optional), path (optional), and shell (required) parameters.

Key features of linux-mcp-server

• Dual execution mode: local process or remote SSH.
• SSH connection pool managed with Caffeine (5‑minute idle expiry).
• Lightweight host configuration via hosts.json.
• Spring Boot native, runnable as mvn spring-boot:run or executable JAR.
• MCP protocol compatible (STREAMABLE HTTP transport).

Use cases of linux-mcp-server

• AI-powered server administration (e.g., restart services, check logs).
• Automated batch command execution across multiple Linux hosts.
• Integrating shell scripting capabilities into MCP‑compatible chatbots.

FAQ from linux-mcp-server

What runtime does linux-mcp-server require?

Java 17+ and Maven 3.6+ (or the bundled Maven wrapper). The target hosts must have SSH service enabled.

How are remote host credentials handled?

Credentials are stored in plain text inside hosts.json. The README advises against committing production credentials; use environment variables or a secure config store for sensitive environments.

Does the server verify SSH host keys?

No. It uses PromiscuousVerifier which skips host key verification. For production, replace with a known‑hosts list to prevent man‑in‑the‑middle attacks.

What is the default transport and port?

The server uses STREAMABLE HTTP transport and listens on port 3001 at the /mcp endpoint. Both can be changed in application.yml.

How long are SSH connections cached?

SSH connections are cached by Caffeine with a default idle timeout of 5 minutes. The cache duration and maximum size can be adjusted in RemoteShellService.