License: MIT Status: Pre-release AI-Ready

ssh-mcp is a simple, secure, and structured CLI tool that enables AI agents and developers to execute JSON-based commands over SSH using the Model Context Protocol (MCP).

The missing bridge between AI and ops.

It acts as a bridge between AI systems (like Claude, LLaMA, GPT) and real-world system operations, allowing tools, prompts, and resource-based interactions through a structured protocol.

🚧 Under active development – MVP Bash implementation available. Go version and package manager support coming soon.

SSH works great for people. But for AI agents and automated devtools?

• There's no structure — just raw text output
• No arguments, schemas, or results
• No streaming, prompting, or metadata

Result: AI agents can't reliably automate remote tasks. Devtools can't reason with responses. And humans must glue everything together.

ssh-mcp makes SSH structured, predictable, and AI-friendly.

• Wrap any remote tool as a JSON-based callable
• Interact with remote machines using structured requests
• Return consistent results with explanations and suggestions
• Secure-by-default using existing SSH keys

If you're building:

• AI tools that talk to real infrastructure
• Developer copilots that touch live servers
• Secure automations that need structured control

...then ssh-mcp helps you move fast without sacrificing control or safety.

• 💻 Developers: Structured command execution over SSH
• 🤖 AI Agents (Claude, GPT, LLaMA): Natural language → structured tool invocation
• 🛠️ Automation: Run predefined tools, long-running ops, and observability
• 👨‍💻 Replit / Cursor / AutoGPT: Drop-in remote tool layer

{
 "tool": "string",
 "args": {
 "property1": "value1"
 },
 "conversation_id": "uuid",
 "context": {
 "user_intent": "string",
 "reasoning": "string"
 }
}

{
 "conversation_id": "uuid",
 "status": { "code": 0, "message": "Success" },
 "result": { "property1": "value1" },
 "explanation": "string",
 "suggestions": [
 { "tool": "string", "description": "string" }
 ],
 "error": {
 "code": "string",
 "message": "string",
 "details": {}
 }
}

# 1. Install
git clone https://github.com/sameehj/ssh-mcp.git
cd ssh-mcp
chmod +x install.sh
./install.sh
# 2. Run a tool
echo '{"tool":"system.info"}' | ssh-mcp user@host

Note: Package manager support (brew, apt, scoop) is planned for future releases.

• SSH access to the target system
• Bash and jq installed on remote machine
• Key-based auth recommended

• Full MCP Protocol support
• Tools, prompts, and resource handling
• Conversation tracking and AI context embedding
• Structured error handling, suggestions, explanations
• Shell completions, self-discovery, tool schemas

• meta.discover: List tools
• meta.describe: Tool descriptions
• meta.schema: Tool input schema

• system.info: OS, CPU, memory
• system.health: Disk, load, uptime

• file.read, file.write, file.list, file.find

• process.list, process.info

• network.status, network.route

• resource.get, resource.list, resource.create

• longRunning.backup, longRunning.scan, longRunning.download

import json, subprocess, uuid
class McpClient:
 def __init__(self, server):
 self.server = server
 self.conversation_id = str(uuid.uuid4())
 def execute_tool(self, tool_name, args=None, user_intent=None):
 payload = {
 "tool": tool_name,
 "args": args or {},
 "conversation_id": self.conversation_id,
 }
 if user_intent:
 payload["context"] = {"user_intent": user_intent}
 result = subprocess.run([
 "ssh", self.server, "./mcp.sh"
 ], input=json.dumps(payload).encode(), stdout=subprocess.PIPE)
 return json.loads(result.stdout)

Use ssh-mcp in conversational loops or LLaMA-based shells:

while true; do
 echo -n "mcp > "
 read CMD
 echo $CMD | ssh-mcp user@host
done

Pair this with a local LLM (e.g. LLaMA) to enable:

"Check CPU usage" → { "tool": "system.monitor" }

• ✅ Bash-based MVP (mcp.sh)
• 🚧 Go binary version (ssh-mcp)
• 🚧 Streaming support for long-running tools
• 🚧 Resource references: inline or URI-based
• 🚧 Prompt + tool hybrid execution
• 🚧 Plugin architecture for third-party tools
• 🚧 Package manager support (brew, apt, scoop)
• 🚧 Shell completions and --discover/--describe
• 🚧 Integration with Claude, Cursor, Replit AI agents

MIT License — see LICENSE file for details.

SSH-MCP Architecture

• MCP Protocol (early-stage spec)
• MCP Specification (draft)
• ClaudeMCP (conceptual integration)
• KernelFaaS (eBPF backend)

Want to contribute tools, prompts, or ideas? Want to use ssh-mcp with your AI shell, devtool, or infra layer?

Let's build it together. Star the repo, fork it, or open an issue.

ssh-mcp is more than a CLI — it's a protocol for building intelligent, secure interfaces between humans, AI, and machines.

• ⭐ Star the repo
• 🛠️ Contribute a tool or prompt
• 💬 Tell us what you're building

This is the terminal AI deserves.