linux
support execute shell on a remote linux or local machine
claude mcp add --transport stdio martindai-linux-mcp-server docker run -i martindai-linux-mcp-server:latest \ --env JAVA_OPTS="Optional JVM options" \ --env SPRING_PROFILES_ACTIVE="default"
How to use
This MCP server exposes a tool named executeShell that enables safe execution of shell commands on local or remote Linux hosts through the MCP protocol. It automatically determines whether to run commands locally or over SSH to remote hosts, utilizes a connection pool for SSH sessions, and returns standard output and error logs to the MCP client. Clients such as Claude Desktop can connect to the MCP endpoint to discover and invoke executeShell by specifying the target machine (machineIp), the execution directory (path), and the full command (shell). The server is built with Spring Boot and Spring AI, and registers the MCP tool via the spring-ai-starter-mcp-server-webmvc integration, supporting STREAMABLE HTTP channels for real-time communication.
How to install
Prerequisites:
- Java 17+
- Maven 3.6+ (or use the provided Maven Wrapper)
- Access to a Linux host reachable via SSH for remote execution
Install steps:
-
Clone the repository: git clone <repository-url> cd linux-mcp-server
-
Configure remote hosts: edit src/main/resources/hosts.json to specify remote Linux hosts and SSH credentials.
-
Build and run locally (development): mvn spring-boot:run
or using the wrapper if available
-
Build package and run as a JAR (production): mvn clean package java -jar target/linux-mcp-server-1.0.0.jar
-
By default the MCP endpoint is exposed at: http://localhost:3001/mcp
Optionally, you can containerize the server and run via Docker using the provided docker config in mcp_config.
Additional notes
Tips and notes:
- Secure credentials: avoid storing plain passwords in hosts.json for production. Use key-based SSH authentication or external secret management.
- Host verification: the README suggests a permissive host verifier is used; for production, replace with a known-hosts verification strategy to prevent MITM attacks.
- SSH cache: the server uses a caching mechanism for SSH connections (adjust CACHE_DURATION_MINUTES and MAX_CACHE_SIZE as needed).
- If you modify application.yml (server port or MCP endpoint), ensure MCP clients are updated accordingly.
- When integrating with AI assistants, ensure the client configuration points to http://localhost:3001/mcp and that the assistant is configured to provide machineIp, path, and shell for executeShell.
