linux-app-deployer

Linux Deployer MCP Server

This is a FastMCP server for managing and deploying applications on Linux systems. It provides a secure, structured interface for running system commands, managing packages, and deploying containerized applications.

Overview

The Linux Deployer MCP Server is designed to facilitate application deployment workflows through a set of well-defined tools that interact with the host Linux system. This server supports both local development and production deployment scenarios.

Security Notice

⚠️ Important: This server allows executing commands on the host Linux system. Exercise caution when deploying in production environments and ensure proper authentication and authorization controls are in place.

---

Local Development

This section covers setting up and running the Linux Deployer MCP Server for local development purposes.

Prerequisites

• Python 3.8 or higher
• uv package manager (recommended) or pip

Installation

1. Clone the repository (if not already done):

   git clone https://github.com/ysonawan/linux-app-deployer.git
   cd linux-app-deployer

1. Install the uv package manager (recommended for development):

   curl -LsSf https://astral.sh/uv/install.sh | sh

1. Install project dependencies:

   uv pip install -r requirements.txt

Alternatively, if using pip: ``bash python3 -m venv venv source venv/bin/activate pip install -r requirements.txt ``

Running the Server Locally

Using FastMCP (recommended): ``bash fastmcp run server.py ``

Direct execution: ``bash uv run python server.py ``

Development Workflow

After starting the server, you can interact with the available tools through the MCP client interface. The server will listen for incoming requests and execute the appropriate tool functions.

For debugging and development purposes, check the logs directory for detailed execution information: ``bash tail -f logs/app.log ``

---

Production Deployment

This section provides comprehensive instructions for deploying the Linux Deployer MCP Server in a production environment. The deployment includes setting up the application code, configuring Nginx with SSL, and managing the service using systemd.

Prerequisites

• Ubuntu/Debian-based Linux server with root or sudo access
• Domain name with DNS configured to point to the server
• Nginx web server installed
• Python 3.8 or higher

Deployment Architecture

The production deployment architecture consists of:

• Application Server: FastMCP server running as a systemd service
• Reverse Proxy: Nginx configured with SSL/TLS encryption
• Service Management: Systemd for automatic service initialization and monitoring

---

Step 1: GitHub SSH Key Setup

Important: Before cloning the repository, ensure the remote server can authenticate with GitHub using SSH keys.

1.1 Generate SSH Key Pair (if not already present)

On the remote server, generate a new SSH key pair: ``bash ssh-keygen -t ed25519 -C "mcp@famvest.online" -f ~/.ssh/id_ed25519 -N "" ``

Or if you prefer RSA: ``bash ssh-keygen -t rsa -b 4096 -C "mcp@famvest.online" -f ~/.ssh/id_rsa -N "" ``

1.2 Get Your Public Key

Display the public key: ```bash cat ~/.ssh/id_ed25519.pub

or for RSA:

cat ~/.ssh/id_rsa.pub

Copy the entire output (starts with `ssh-ed25519` or `ssh-rsa`).

#### 1.3 Add Public Key to GitHub

1. Go to GitHub Settings: https://github.com/settings/keys
2. Click **"New SSH key"**
3. Add a title (e.g., "MCP Server - famvest.online")
4. Paste the public key in the **Key** field
5. Set **Key type** to "Authentication Key"
6. Click **"Add SSH key"**

#### 1.4 Test SSH Connection

Verify the SSH connection works:

ssh -T git@github.com ```

You should see: Hi <your-username>! You've successfully authenticated, but GitHub does not provide shell access.

1.5 Configure Git (Optional but Recommended)

Set your Git identity on the server: ``bash git config --global user.name "MCP Server" git config --global user.email "mcp@famvest.online" ``

---

Step 2: Repository Setup

Clone the application repository to the designated production directory.

Navigate to the deployment directory and set up the folder structure: ``bash cd /opt sudo mkdir -p mcp/repos sudo chown $(whoami):$(whoami) mcp cd mcp ``

Clone the repository: ``bash git clone https://github.com/ysonawan/linux-app-deployer.git cd linux-app-deployer ``

The application code is now located at /opt/mcp/linux-app-deployer.

---

Step 3: Web Server and SSL Configuration

Configure Nginx as a reverse proxy with SSL/TLS encryption to securely expose the MCP server.

3.1 Verify DNS Resolution

Before setting up SSL, ensure your domain resolves correctly: ``bash dig mcp.adminhub.upvaly.com +short ``

3.2 Install and Configure Certbot

Install Certbot for automated SSL certificate management: ``bash sudo apt install -y certbot python3-certbot-nginx certbot --version ``

3.3 Validate Nginx Configuration

Test the current Nginx setup: ``bash sudo nginx -t ``

Reload Nginx to apply any pending changes: ``bash sudo systemctl reload nginx ``

3.4 Obtain SSL Certificate

Obtain an SSL certificate for your domain using Certbot: ``bash sudo certbot --nginx -d mcp.adminhub.upvaly.com ``

Follow the interactive prompts to configure automatic renewal and other options.

3.5 Deploy Nginx Configuration

Setup secret key for api authentication ``bash vi /etc/nginx/nginx.conf ` Add the following line within the http block to define the API key: ` map $http_x_api_key $mcp_api_key_valid { default 0; "your-secret-api-key-here" 1; } ``

Copy the provided Nginx configuration file: ``bash cd /etc/nginx/sites-available sudo cp /opt/mcp/linux-app-deployer/prod-deployment-scripts/mcp.adminhub.upvaly.com . ``

Enable the site by setting up symlinks and removing defaults: ``bash cd /etc/nginx/sites-enabled sudo rm -f default sudo ln -sf /etc/nginx/sites-available/mcp.adminhub.upvaly.com mcp.adminhub.upvaly.com ``

3.6 Final Nginx Validation

Verify the updated configuration and reload: ``bash sudo nginx -t sudo systemctl reload nginx ``

---

Step 4: Application Server Setup

Configure the MCP server application with environment variables and dependencies.

4.1 Environment Configuration

Create a .env file from the example template (if available): ``bash cd /opt/mcp/linux-app-deployer cp .env.example .env ``

Edit the .env file with your production settings: ``bash nano .env ``

Common configuration parameters:

• LOG_LEVEL: Set to INFO or ERROR for production
• SERVER_PORT: Port for the internal server
• API_KEY: Secure API key for authentication

4.2 Install the uv Package Manager

Install the high-performance uv package manager: ``bash curl -LsSf https://astral.sh/uv/install.sh | sh ``

Reload your shell environment: ```bash source ~/.bashrc

Verify installation

which uv

Expected output: /root/.local/bin/uv

#### 4.3 Install Project Dependencies

Install all Python dependencies using `uv`:

cd /opt/mcp/linux-app-deployer uv pip install -r requirements.txt ```

Alternatively, if using traditional pip: ``bash python3 -m venv venv source venv/bin/activate pip install -r requirements.txt ``

---

Step 5: Systemd Service Configuration

Set up the MCP server as a systemd service for automatic startup and monitoring.

5.1 Install Service File

Copy the systemd service configuration: ```bash sudo cp /opt/mcp/linux-app-deployer/prod-deployment-scripts/linux-app-deployer.service /etc/systemd/system/

#### 5.2 Enable and Start the Service

Reload the systemd daemon to recognize the new service:

sudo systemctl daemon-reload ```

Enable the service to start automatically on boot: ``bash sudo systemctl enable linux-app-deployer.service ``

Start the service: ```bash sudo systemctl restart linux-app-deployer.service

#### 5.3 Verify Service Status

Check the current status of the service:

sudo systemctl status linux-app-deployer.service

View recent logs:

sudo journalctl -u linux-app-deployer.service -n 50 --no-pager

Follow logs in real-time:

sudo journalctl -u linux-app-deployer.service -f

---

### Deployment Completion

The Linux Deployer MCP Server is now running in production. The application is accessible through your configured domain with SSL/TLS encryption.

**Verify the deployment**:

curl https://mcp.famvest.online/health ```

Monitoring:

• Use systemctl status to check service health
• Monitor logs via journalctl for debugging
• Configure log rotation if necessary

For ongoing maintenance, update the application periodically: ```bash cd /opt/mcp/linux-app-deployer git pull uv pip install -r requirements.txt sudo systemctl restart linux-app-deployer.service

---

## Cursor and Claude Desktop Integration

This section explains how to configure the Linux Deployer MCP Server with Cursor or Claude Desktop to enable local AI assistance with deployment tasks.

### Configuration for Cursor

1. **Open Cursor Settings**:
   - Open Cursor and go to `Settings` (or `Cursor` > `Settings` on macOS)
   - Navigate to the `Features` tab and locate the MCP section

2. **Add MCP Server Configuration**:

   **With API Key (if authentication is enabled)** - **Recommended Method**:

{ "mcpServers": { "linux-app-deployer": { "command": "npx", "args": [ "mcp-remote", "https://mcp.adminhub.upvaly.com/mcp", "--header", "X-API-Key: your-secret-api-key-here" ] } } } ```

Replace your-secret-api-key-here with your actual API key.

1. Restart Cursor:

• Close and reopen Cursor to apply the configuration
• The MCP server connection will be established automatically

Configuration for Claude Desktop

1. Locate Configuration File:

• On macOS, the configuration file is located at:

     ~/Library/Application Support/Claude/claude_desktop_config.json

• On Windows, the file is typically at:

     %APPDATA%\Claude\claude_desktop_config.json

• On Linux, the file is typically at:

     ~/.config/Claude/claude_desktop_config.json

1. Edit Configuration File:

• Open the claude_desktop_config.json file in your text editor

With API Key (if authentication is enabled) - Recommended Method: ``json { "mcpServers": { "linux-app-deployer": { "command": "npx", "args": [ "mcp-remote", "https://mcp.adminhub.upvaly.com/mcp", "--header", "X-API-Key: your-secret-api-key-here" ] } } } ``

Replace your-secret-api-key-here with your actual API key.

1. Restart Claude Desktop:

• Close and reopen Claude Desktop
• The MCP server connection will be established automatically

API Key Setup for Cursor/Claude Desktop

To use the API key with Cursor or Claude Desktop:

1. Get the API Key: Contact your system administrator for the secret API key set in the Nginx configuration

1. Update Your Configuration: Replace your-secret-api-key-here in the config with your actual API key:

    "linux-app-deployer": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.adminhub.upvaly.com/mcp",
        "--header",
        "X-API-Key: your-secret-api-key-here"
      ]
    }

Replace your-secret-api-key-here with your actual API key.

1. Keep it Secure:

• Store your configuration files with restricted permissions
• For Claude Desktop: chmod 600 ~/Library/Application\ Support/Claude/claude_desktop_config.json
• For Cursor: Ensure your settings file is not world-readable
• DO NOT commit API keys to version control systems
• Consider using a .env file approach if your config file is shared

Using the MCP Server in Cursor/Claude Desktop

Once configured, you can interact with the Linux Deployer MCP Server by:

• Mentioning deployment tasks in your conversations
• Asking for help with application deployment workflows
• Requesting system command execution through the available tools
• Getting AI-assisted guidance on deployment best practices

The AI assistant will have access to the tools provided by the Linux Deployer MCP Server and can help you automate and manage your Linux application deployments.

Troubleshooting Connection Issues

If the MCP server connection is not established:

1. Check MCP Server Status:

• On the production server, verify the service is running:

     sudo systemctl status linux-app-deployer.service

2.Review Logs:

• Check Claude Desktop or Cursor logs for connection errors
• Review the MCP server logs on the remote machine:

     sudo journalctl -u linux-app-deployer.service -f

3.Verify Configuration Syntax:

• Ensure the JSON configuration is properly formatted
• Reload Cursor or Claude Desktop after making changes

4.API Key Authentication Issues (if authentication is enabled):

• 401 Unauthorized: The API key is missing or invalid
• Verify the MCP_API_KEY environment variable is set in your config
• Confirm the API key value matches the one configured in Nginx
• Test with curl:

       curl -H "X-API-Key: your-actual-api-key" https://mcp.famvest.online/mcp

• Connection Fails After Configuration Update: Configuration changes may not take effect immediately
• Restart Cursor or Claude Desktop completely (not just close and reopen)
• Clear any cached data in the application settings
• Verify the JSON configuration syntax is valid

• 401 Error in Logs: The API key doesn't match Nginx configuration
• Double-check that the API key in your Cursor/Claude Desktop config matches the one set in /etc/nginx/sites-available/mcp.famvest.online
• Ensure there are no extra spaces or special characters in the API key

1. Configuration File Issues:

• Verify the JSON syntax is valid (use a JSON validator if unsure)
• Ensure the file has proper permissions: chmod 600 ~/path/to/config.json
• For Claude Desktop, the exact file path is important—use the full path matching your OS