Troubleshooting¶

Solutions for common issues when installing and using the Linux MCP Server.

Quick Links

Using MCP Inspector
Common Installation Issues
SSH Connection Issues
Platform-Specific Issues
Getting Additional Help

Using MCP Inspector for Debugging¶

The MCP Inspector is an official tool for testing and debugging MCP servers.

Install MCP Inspector:

Note

Requires Node.js to be installed on your system.

npm install -g @modelcontextprotocol/inspector

Run the inspector with your MCP server:

# For pip-installed version
mcp-inspector linux-mcp-server

# For uvx version
mcp-inspector uvx linux-mcp-server

# For development version
cd /path/to/linux-mcp-server
mcp-inspector uv run linux-mcp-server

The inspector provides a web UI where you can:

View all available tools
Test tool calls with different parameters
See real-time request/response data
Debug connection issues
Inspect server capabilities

Local Debugging of Tool Calls¶

You can test MCP server tools locally without Claude Desktop or the inspector.

Method 1: Interactive Python Session¶

# Activate your virtual environment first
source .venv/bin/activate  # Linux/macOS
# OR
.venv\Scripts\activate     # Windows

# Start Python
python

# Import and test tools
>>> from linux_mcp_server.tools import system_info
>>> import asyncio
>>> result = asyncio.run(system_info.get_system_information())
>>> print(result)

Method 2: Create a Test Script¶

Create a file test_tool.py:

import asyncio
from linux_mcp_server.tools import system_info, services

async def main():
    # Test system info tool
    print("=== System Info ===")
    result = await system_info.get_system_information()
    print(result)

    # Test service listing
    print("\n=== Services ===")
    result = await services.list_services()
    print(result)

if __name__ == "__main__":
    asyncio.run(main())

Run it:

python test_tool.py

Method 3: Run pytest in verbose mode¶

# Run specific test
pytest tests/test_system_info.py -v

# Run with output showing
pytest tests/test_system_info.py -v -s

# Run all tests for a module
pytest tests/ -k "system_info" -v

Common Installation Issues¶

"command not found: linux-mcp-server"¶

Cause: The package isn't installed or the installation directory isn't in your PATH.

Solutions:

Verify installation: pip show linux-mcp-server
Try running as module: python -m linux_mcp_server

Check if pip install location is in PATH:

pip show linux-mcp-server | grep Location

Add pip's bin directory to PATH, or use a virtual environment

"No module named 'linux_mcp_server'"¶

Cause: The package isn't installed in the current Python environment.

Solutions:

Ensure you're using the correct Python: which python or where python
Install the package: pip install linux-mcp-server
If using virtual environment, make sure it's activated

"Permission denied" when reading system logs¶

Cause: The user running the MCP server doesn't have permission to read system logs.

Solutions:

Add user to adm or systemd-journal group:

sudo usermod -a -G adm $USER
sudo usermod -a -G systemd-journal $USER

Log out and log back in for group changes to take effect
Only whitelist log files that the user can read in LINUX_MCP_ALLOWED_LOG_PATHS

"Permission denied" when reading a local application log file¶

Cause: If the server throws an error when starting (e.g., PermissionError: [Errno 13] Permission denied: '.../server.log'), it's usually because the log file or its parent directory is owned by a different user (often root due to a previous sudo run).

Solutions:

Verify the current user is the owner of the log directory:
```
ls -ld /home/$USER/.local/share/linux-mcp-server/logs
```
If the owner is not $USER (e.g., if it shows root or a different User ID), reclaim the folder ownership:
```
sudo chown -R $USER:$USER /home/$USER/.local/share/linux-mcp-server/logs
```

Claude Desktop doesn't show the MCP server¶

Common causes:

Syntax error: Validate JSON at https://jsonlint.com/
Wrong file location: See Client Configuration
Command not in PATH: Use full path in command field or ensure command is in PATH
Server won't start: Test command manually; check Claude Desktop logs (~/Library/Logs/Claude/ on macOS, ~/.config/Claude/logs/ on Linux, %APPDATA%\Claude\logs\ on Windows)
Config not reloaded: Completely quit and restart Claude Desktop

ImportError or ModuleNotFoundError during development¶

Cause: Dependencies aren't installed or virtual environment isn't activated.

Solutions:

Ensure virtual environment is activated:

source .venv/bin/activate  # Linux/macOS
.venv\Scripts\activate     # Windows

Reinstall dependencies:

uv sync --group dev
# OR
pip install -e ".[dev]"

SSH Connection Issues¶

"Permission denied (publickey)"¶

Cause: SSH key authentication failed.

Solutions:

Verify key exists and is readable:
```
ls -la ~/.ssh/id_*
```
Test SSH directly with verbose output:
```
ssh -v user@hostname "echo test"
```
The -v flag shows detailed connection info to identify the failure point.

Ensure key is loaded in ssh-agent:

ssh-add -l           # List loaded keys
ssh-add ~/.ssh/id_ed25519  # Add if missing

For containers, verify key ownership:

ls -la ~/.local/share/linux-mcp-server/id_*
# Should be owned by UID 1001
sudo chown 1001:1001 ~/.local/share/linux-mcp-server/id_ed25519

"Host key verification failed"¶

Cause: Remote host is not in your known_hosts file.

Solutions:

Connect manually first to accept the key:

ssh user@hostname
# Type "yes" when prompted to accept the host key

Or disable host key verification (less secure):

"env": {
  "LINUX_MCP_VERIFY_HOST_KEYS": "False"
}

Connection timeouts¶

Cause: Network issues, firewall blocking SSH, or incorrect hostname.

Solutions:

Test basic connectivity:

ping hostname
ssh -o ConnectTimeout=5 user@hostname "echo test"

Increase timeout in client config:

"env": {
  "LINUX_MCP_COMMAND_TIMEOUT": "60"
}

Check firewall rules on both local and remote systems for port 22 (or custom SSH port).

"No such file or directory" for SSH key¶

Cause: The SSH key path is incorrect or key doesn't exist.

Solutions:

Check if the key exists:
```
ls -la ~/.ssh/
```

Generate a new key if needed:

ssh-keygen -t ed25519 -C "your_email@example.com"

Verify LINUX_MCP_SSH_KEY_PATH points to correct file.

Platform-Specific Issues¶

This section explains issues that may be present when using the MCP server to interact with a system that is not compatible.

Linux: "systemctl: command not found"¶

Cause: System doesn't use systemd (very old distributions or non-standard systems).

Solution: This MCP server requires systemd to be available on the target system for certain tools to function properly.

The main use case is to troubleshoot modern RHEL-alike Linux systems (e.g. RHEL 9.x, 10.x, Fedora 40 and above, etc.)
Consider upgrading to a modern Linux distribution (RHEL 7+, Fedora, etc.).

macOS: Limited functionality warnings¶

Cause: Some Linux-specific commands don't exist or behave differently on macOS.

Note: This is expected. The MCP server is designed to diagnose Linux systems (see above).

Some tools may work on macOS, but some may have reduced functionality or not work at all.

Windows: Most or all tools not working¶

Cause: The MCP server relies on Linux-specific tools (systemd, journalctl, etc.) that don't exist on Windows.

Solution: This is expected behavior. The MCP server is not designed to diagnose Windows systems.

On Windows, use the MCP server primarily for:
Remote SSH execution to manage Linux servers
Testing and development
For local Windows management, use a Windows-specific MCP server

Getting Additional Help¶

Check logs: Server logs in ~/.local/share/linux-mcp-server/logs/, Claude Desktop logs (see above)
Enable debug: Set "LINUX_MCP_LOG_LEVEL": "DEBUG" in config, restart your AI Agent (e.g. Claude Desktop)
Test with MCP Inspector: Isolate whether issue is with server or client
Run the MCP server manually: Make sure the MCP server does not crash upon start and is able to receive messages.
Open an issue: https://github.com/rhel-lightspeed/linux-mcp-server/issues
Include:
- Your OS and version
- Python version
- Installation method used
- Error messages and logs
- Steps to reproduce