mcpx
A Model Context Protocol server for complete shell and SSH mastery, enabling command execution, interactive sessions, file transfer, and port forwarding with auditing and policy controls.
What is mcpx?
mcpx is a Model Context Protocol (MCP) server that allows AI assistants like Claude, Cursor, and VS Code to model context protocol server for complete shell and ssh mastery, enabling command execution, interactive sessions, file transfer, and port forwarding with auditing and policy controls.
A Model Context Protocol server for complete shell and SSH mastery, enabling command execution, interactive sessions, file transfer, and port forwarding with auditing and policy controls.
This server falls under the Developer Tools category on MCPgee, the world's largest MCP server directory with 33,000+ servers.
Features
- A Model Context Protocol server for complete shell and SSH m
Use Cases
Maintainer
Works with
Installation
Manual Installation
npx mcpxConfiguration
Configuration Details
claude_desktop_config.json
Performance
Response Metrics
Resource Usage
How to Set Up and Use mcpx
mcpx (relay-shell) is an MCP server that gives AI agents complete shell and SSH mastery — from local command execution and interactive PTY sessions to remote SSH operations, file transfer, port forwarding, and parallel fleet management. It ships with auditing and policy controls so every command is logged, and supports OAuth 2.1 for authenticated deployments. Teams use it to let AI assistants automate infrastructure tasks, run scripts across remote hosts, and manage long-running sessions without context switching.
Prerequisites
- Python 3.12, 3.13, or 3.14
- asyncssh 2.18 or later for SSH operations
- An MCP-compatible client such as Claude Desktop
- SSH key or password access to any remote hosts you plan to connect
- Ubuntu 24.04 LTS or compatible Linux environment (tested platform)
Clone the repository
Download the relay-shell source code from GitHub.
git clone https://github.com/rmednitzer/relay-shell.git
cd relay-shellCreate a virtual environment and install dependencies
Use a Python virtual environment to isolate dependencies, then install the package in editable mode with dev extras.
python3 -m venv .venv
. .venv/bin/activate
pip install -e ".[dev]"Configure the server via environment variables
Copy the example env file and set your policy mode, audit settings, resource bounds, and optional OAuth config. At minimum review the defaults before starting.
cp .env.example .env
# Edit .env with your preferred settings
# e.g. RELAY_SHELL_TRANSPORT=stdio (default)Start the server
Run in stdio mode for local agent use, or set RELAY_SHELL_TRANSPORT=http for HTTP/SSE transport on 127.0.0.1:8080.
# Stdio mode (default)
relay-shell
# HTTP/SSE mode
RELAY_SHELL_TRANSPORT=http relay-shellValidate your configuration
Use the built-in check flags to verify configuration before connecting your MCP client.
relay-shell --check-config
relay-shell --verify-deployAdd the server to your MCP client
Configure Claude Desktop or another MCP client to launch relay-shell via stdio, pointing to the virtualenv binary.
{
"mcpServers": {
"relay-shell": {
"command": "/path/to/relay-shell/.venv/bin/relay-shell"
}
}
}mcpx Examples
Client configuration
Claude Desktop stdio configuration for relay-shell using the virtualenv binary.
{
"mcpServers": {
"relay-shell": {
"command": "/path/to/relay-shell/.venv/bin/relay-shell"
}
}
}Prompts to try
Example prompts leveraging local shell, SSH, and fleet management capabilities.
- "Run 'df -h' on the local machine and show disk usage"
- "SSH into web01.example.com and check nginx status"
- "Upload /local/config.yaml to /etc/app/config.yaml on server01 via SSH"
- "Open a port forward from local 5432 to db01.internal:5432"
- "Fan out 'uptime' across all hosts in my server list and show results"
- "Show me the last 20 audit log entries for this session"Troubleshooting mcpx
SSH connection fails with 'No hostkey found' or key rejection
Run 'relay-shell --check-config' to validate SSH settings. Use the ssh_keyscan tool to pre-populate known hosts, or set the appropriate trust policy in your .env file.
Commands hang and never return output
relay-shell applies configurable timeouts and output limits. Check your .env for RELAY_SHELL_TIMEOUT settings. For long-running tasks use shell_spawn to start a persistent PTY session and poll with session_recv.
Permission denied when running commands in policy-restricted mode
Review the policy mode set in .env. The server supports multiple policy levels that restrict which commands are allowed. Adjust the policy or whitelist specific commands as documented in docs/deployment.md.
Frequently Asked Questions about mcpx
What is mcpx?
mcpx is a Model Context Protocol (MCP) server that model context protocol server for complete shell and ssh mastery, enabling command execution, interactive sessions, file transfer, and port forwarding with auditing and policy controls. It connects AI assistants to external tools and data sources through a standardized interface.
How do I install mcpx?
Follow the installation instructions on the mcpx GitHub repository. Clone the repo, install dependencies, and add the server config to your AI client.
Which AI clients work with mcpx?
mcpx works with all major MCP-compatible AI clients including Claude Desktop, Claude Code, Cursor, VS Code (GitHub Copilot), Windsurf, and Cline.
Is mcpx free to use?
Yes, mcpx is open source and available under the Apache 2.0 license. You can use it freely in both personal and commercial projects.
mcpx Alternatives — Similar Developer Tools Servers
Looking for alternatives to mcpx? Here are other popular developer tools servers you can use with Claude, Cursor, and VS Code.
Ecc
★ 188.2kThe agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
Javaguide
★ 155.8kJava 面试 & 后端通用面试指南，覆盖计算机基础、数据库、分布式、高并发、系统设计与 AI 应用开发
Gemini CLI
★ 104.5kA secure MCP server that wraps the Google Gemini CLI, allowing clients to query Gemini models using local OAuth sessions without requiring an API key. It provides tools for model interaction and diagnostics with built-in protection against command in
Awesome MCP Servers
★ 87.3k⭐ Curated list of Model Context Protocol (MCP) servers - tools that extend Claude Desktop, Cursor, Windsurf, and other MCP clients with custom capabilities.
MCP Servers
★ 86.0kModel Context Protocol Servers
CC Switch
★ 77.5kA cross-platform desktop All-in-One assistant for Claude Code, Codex, OpenCode, OpenClaw, Gemini CLI & Hermes Agent. Only official website: ccswitch.io
Browse More Developer Tools MCP Servers
Explore all developer tools servers available in the MCPgee directory. Each server includes setup guides for Claude, Cursor, and VS Code.
Set Up mcpx in Your Editor
Choose your AI client for step-by-step setup instructions.
Quick Config Preview
Add this to your claude_desktop_config.json or .cursor/mcp.json
Ready to use mcpx?
Browse our complete directory of 33,000+ MCP servers, read setup guides for your editor, and start building with the Model Context Protocol.