Kasm MCP Server v2

A Model Context Protocol (MCP) server that enables AI agents to manage and interact with Kasm Workspaces containerized desktop infrastructure. This server provides a standardized interface for LLMs to create, manage, and execute commands within Kasm sessions.

🚀 Quick Start

# Clone the repository
git clone https://github.com/roguedev-ai/kasm-mcp-server-v2.git
cd kasm-mcp-server-v2

# Run the automated setup script
./setup-prerequisites.sh

# Choose option 1 for NPM/Python mode (recommended for Cline)
# Configure your Kasm API credentials when prompted

# Start the server
source venv/bin/activate
python -m src

📚 Documentation

• Quick Start Guide - Get up and running in 5 minutes
• Installation Guide - Detailed installation instructions
• Tool Reference - Complete reference for all 21 available tools
• Suggested Prompts - Example prompts for effective usage
• Troubleshooting Guide - Common issues and solutions
• Cline Integration Guide - Configure Cline to use this MCP server
• LLM Integration Guide - Integrate with any MCP-compatible LLM
• Architecture Documentation - System design and components
• Security Documentation - Security features and best practices

✨ Features

• 🔧 Session Management - Create, destroy, and monitor Kasm workspace sessions
• 💻 Command Execution - Execute commands inside Kasm containers with security boundaries
• 📁 File Operations - Read and write files within Kasm sessions
• 👥 User Management - Create and manage Kasm users
• 🔒 Security - MCP Roots security mechanism for safe file operations
• 🔌 Multiple Deployment Options - NPM/Python or Docker deployment

🛠️ Available Tools

The server provides 21 tools organized into categories:

Session Management (8 tools)

• create_kasm_session - Launch a new Kasm workspace
• destroy_kasm_session - Terminate a session
• get_session_status - Check session status
• list_user_sessions - List your active sessions
• list_all_sessions - List all system sessions (admin)
• pause_kasm_session - Pause a session to free resources
• resume_kasm_session - Resume a paused session
• get_session_screenshot - Capture session screenshot

Command & File Operations (3 tools)

• execute_kasm_command - Execute shell commands in sessions
• read_kasm_file - Read file contents from sessions
• write_kasm_file - Write content to files in sessions

User Management (6 tools)

• get_kasm_users - List all users
• create_kasm_user - Create new user accounts
• get_kasm_user - Get specific user details
• update_kasm_user - Update user information
• delete_kasm_user - Remove users from system
• logout_kasm_user - Logout all user sessions

Monitoring & Performance (3 tools)

• get_session_frame_stats - Frame rendering statistics
• get_session_bottleneck_stats - CPU/network bottleneck analysis
• get_session_recordings - Access session recordings

System Information (1 tool)

• get_available_workspaces - List available workspace images

See the Tool Reference for complete details on all tools.

📦 Installation Options

Option 1: Automated Setup (Recommended)

Use the setup-prerequisites.sh script for automated installation:

./setup-prerequisites.sh

Choose from:

1. NPM/Python Mode - Direct execution with npm support (best for Cline)
2. Docker Mode - Containerized deployment
3. Both - Install prerequisites for both modes

Option 2: Manual Installation

See the Installation Guide for manual setup instructions.

🔧 Configuration

Create a .env file with your Kasm credentials:

KASM_API_URL=https://your-kasm-instance.com
KASM_API_KEY=your_api_key_here
KASM_API_SECRET=your_api_secret_here
KASM_USER_ID=default
KASM_ALLOWED_ROOTS=/home/kasm-user
LOG_LEVEL=INFO

🧪 Testing

Run the diagnostic test to verify your installation:

python test_server.py

🐛 Troubleshooting

Recent Fixes

• FastMCP Initialization Error - Fixed in commit c95882e (see MCP_SDK_COMPATIBILITY_FIX.md)
• Import Issues - Resolved with official MCP SDK migration

Common Issues

1. "No module named 'mcp'" - Install the MCP SDK: pip install mcp
2. Environment variables not set - Check your .env file configuration
3. Server won't start - Run python test_server.py for diagnostics

🤝 Contributing

Contributions are welcome! Please read our contributing guidelines and submit pull requests to the repository.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🔗 Resources

• Kasm Workspaces Documentation
• Model Context Protocol Documentation
• Cline (Claude Dev) Extension

📧 Support

For issues and questions:

• Open an issue on GitHub
• Check existing documentation in the /docs folder
• Review the troubleshooting section above

---

Current Version: 2.0.1
Last Updated: September 10, 2025
Status: ✅ Production Ready