Content
# Linux MCP Server
A Spring Boot and Spring AI based Model Context Protocol (MCP) server that enables secure Shell command execution on local and remote Linux hosts. Through the MCP standard interface, it can be directly connected to AI assistants like Claude Desktop, expanding their operation and maintenance capabilities.
## Table of Contents
- [Introduction](#introduction)
- [Key Features](#key-features)
- [Quick Start](#quick-start)
- [Configuration](#configuration)
- [Integration with AI Assistants](#integration-with-ai-assistants)
- [Security Recommendations](#security-recommendations)
- [Development and Debugging](#development-and-debugging)
- [License](#license)
## Introduction
Linux MCP Server encapsulates Shell execution into an MCP tool called `executeShell`, which is automatically registered to the MCP Server by Spring AI. Clients can execute scripts on local or remote Linux machines by specifying the target host and command through standard MCP calls, and return standard output and error logs.
## Key Features
- **Dual-mode Execution**: Automatically determines the command execution location, supporting local process scheduling and remote SSH execution.
- **Connection Pool Management**: Based on Caffeine cache to reuse SSH connections, with a default 5-minute automatic expiration and cleanup.
- **Lightweight Configuration**: Uses a simple `hosts.json` to maintain a list of remote hosts, which can take effect with a hot restart.
- **Spring Boot Native Integration**: Out-of-the-box `mvn spring-boot:run` / executable JAR deployment method, listening on port `3001` by default.
- **MCP Protocol Compatibility**: Depends on `spring-ai-starter-mcp-server-webmvc`, supports STREAMABLE HTTP channels, and adapts to mainstream MCP clients.
## Quick Start
### Preparation
- Java 17+
- Maven 3.6+ (recommended to use the built-in `./mvnw`/`mvnw.cmd` of the repository)
- Target Linux host with SSH service
### Get Code
```bash
git clone <repository-url>
cd linux-mcp-server
```
### Configure Remote Host
Edit `src/main/resources/hosts.json`:
```json
[
{
"ip": "192.168.1.100",
"username": "devops",
"password": "your_password"
}
]
```
- `ip`: Target host address, which needs to correspond to `machineIp` in `executeShell`.
- `username`/`password`: SSH login credentials, currently using password authentication, which can be extended to key login in the code.
> ⚠️ It is recommended not to submit production credentials to the repository, and use environment variables or configuration centers to manage sensitive information.
### Start Service
Run directly in the development environment:
```bash
mvn spring-boot:run
```
Or package and run independently:
```bash
mvn clean package
java -jar target/linux-mcp-server-1.0.0.jar
```
After startup, the MCP access point is exposed at `http://localhost:3001/mcp` by default.
## Configuration
Key configurations are concentrated in `src/main/resources/application.yml`:
```yaml
server:
port: 3001 # MCP Server listening port
spring.ai.mcp.server:
name: linux-mcp-server
version: 1.0.0
protocol: STREAMABLE # Use streamable HTTP transport
streamable-http:
mcp-endpoint: /mcp # MCP entry path
```
If customization is needed:
- Remember to update the MCP client configuration synchronously when changing the port or `mcp-endpoint`.
- If you need to connect to more hosts, simply add entries to `hosts.json` and restart the service.
## Integration with AI Assistants
Taking Claude Desktop as an example, you can add it to its `claude_desktop_config.json`:
```json
{
"mcpServers": [
{
"name": "linux-mcp-server",
"type": "http",
"command": "http",
"args": ["http://localhost:3001/mcp"]
}
]
}
```
After successful connection, Claude will automatically discover the tool `executeShell`:
- `machineIp` (optional): Empty or local address to execute local machine commands.
- `path` (optional): Command execution directory, default is `/`.
- `shell` (required): The complete command that needs to be executed.
## Security Recommendations
- **Credential Management**: `hosts.json` saves passwords in plaintext, only used for development or controlled environments; use key authentication or external secure storage in production environments.
- **Host Verification**: Currently uses `PromiscuousVerifier` to skip host fingerprint verification, replace with a known host list before deploying to production to prevent man-in-the-middle attacks.
- **Permission Minimization**: Create a restricted user for remote machines, avoid using the `root` account, and limit the range of executable commands.
- **Network Restrictions**: Restrict access sources of MCP Server and target hosts through firewalls/security groups.
## Development and Debugging
- The code structure is mainly located in `src/main/java/com/doodl6/mcp/linux`, which can be extended with new tool methods as needed.
- If you need to adjust the SSH cache strategy, you can modify `CACHE_DURATION_MINUTES` and `MAX_CACHE_SIZE` in `RemoteShellService`.
- It is recommended to manually trigger an `executeShell` (local and remote each once) after modification to verify output and error handling logic.
## License
The project is open-sourced under the [MIT License](LICENSE), which allows free use and secondary development.
