nikhildx/umcp

Ubuntu OS MCP Server (UMCP)

A secure, modular MCP (Model Context Protocol) server for Ubuntu Linux system administration. Enables AI assistants and automation tools to safely interact with Ubuntu systems through authenticated, whitelisted operations.

Features

• Multi-Protocol Support: stdio, HTTP/REST, and SSE (Server-Sent Events)
• Comprehensive System Operations: Disk usage, process management, file operations, git commands, package management, and more
• Security First: API key/JWT authentication, RBAC, command/path whitelisting, audit logging
• MCP Compliant: Full support for Tools, Resources, and Prompts
• OpenAPI 3.0: Auto-generated REST API documentation
• Modular Architecture: Clean separation of concerns for easy extension

Quick Start

Installation

# Clone the repository
git clone https://github.com/umcp/umcp.git
cd umcp

# Create virtual environment
python3.11 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -e .

# Install development dependencies
pip install -e ".[dev]"

Configuration

# Copy example configuration
cp config/server.example.yaml config/server.yaml

# Edit configuration
nano config/server.yaml

Running the Server

# Stdio mode (for local MCP clients)
umcp --transport stdio

# HTTP mode (REST API + SSE)
umcp --transport http --port 8000

# With custom config
umcp --config config/server.yaml

Usage Examples

Using with MCP CLI Client

# List available tools
mcp-client list-tools --server stdio://umcp

# Execute a tool
mcp-client call-tool get_disk_usage --server stdio://umcp

Using HTTP REST API

# Get authentication token
curl -X POST http://localhost:8000/auth/token \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "secret"}'

# Call a tool
curl -X POST http://localhost:8000/tools/get_disk_usage \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"human_readable": true}'

Available Tools

• System Information: get_disk_usage, get_memory_info, get_system_info
• File Operations: list_directory, change_permissions, change_ownership
• Process Management: list_processes, get_process_info
• Network: get_network_stats, netstat_query, lsof_query
• Git Operations: git_clone, git_pull, git_status, git_log
• Package Management: apt_update, apt_install
• Service Management: systemctl_control, systemctl_status
• Maintenance: cleanup_logs

Security

UMCP implements multiple security layers:

• Authentication: API key or JWT token-based authentication
• Authorization: Role-based access control (RBAC)
• Whitelisting: Commands, paths, and users must be explicitly allowed
• Audit Logging: All operations are logged for security review
• Input Validation: Prevents command injection and path traversal attacks

See for details.

Development

Running Tests

# Run all tests
pytest

# Run with coverage
pytest --cov=umcp --cov-report=html

# Run specific test categories
pytest -m "not slow"
pytest -m integration
pytest -m security

Code Quality

# Format code
black umcp tests

# Lint code
ruff check umcp tests

# Type checking
mypy umcp

Pre-commit Hooks

# Install pre-commit hooks
pre-commit install

# Run manually
pre-commit run --all-files

Architecture

umcp/
├── core/           # Core server, config, models
├── transports/     # stdio, HTTP, SSE adapters
├── security/       # Auth, authorization, validation
├── handlers/       # MCP tools, resources, prompts
├── services/       # System operation services
└── utils/          # Shared utilities

See for details.

Documentation

Contributing

Contributions are welcome! Please read for guidelines.

License

MIT License - see for details.

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Documentation: Read the Docs