MCP Shellkeeper

🚀 MCP ShellKeeper

Enable AI assistants with persistent terminal sessions and file transfer capabilities, allowing seamless SSH operations, command execution, and file transfer on servers.

🚀 Quick Start

MCP ShellKeeper transforms AI assistants into stateful operators. You can install it via npm and configure it in your AI assistant settings. After restarting the AI assistant, you're ready to use it for server operations through natural language interactions.

✨ Features

🔄 Stateful Execution

Traditional AI (Stateless)

You: "SSH to server"
AI: ❌ Command hangs forever

You: "List files"
AI: ❌ Runs on local, not server

ShellKeeper (Stateful)

You: "Connect to my server"
AI: ✅ Establishes SSH session

You: "What files are there?"
AI: ✅ Lists files on server

You: "Go to the logs folder"
AI: ✅ Changes to /var/log

You: "Show me recent errors"
AI: ✅ Displays log content

The AI maintains full context between your questions!

🎯 Persistent Sessions

Natural Conversation Flow

You: "SSH to production server"
AI: ✅ Connected to prod-01
    Session: prod-01

You: "How much disk space left?"
AI: ✅ 45GB available
    (same session, no re-auth)

You: "Show me today's logs"
AI: ✅ Displaying logs...
    (same session continues)

You: "Restart the API service"
AI: ✅ Service restarted
    (still same session!)

The AI remembers everything:

• ✅ Your SSH connections
• ✅ Current directories
• ✅ Environment variables
• ✅ All previous context

📁 Seamless File Transfer

Just Ask in Natural Language

You: "Upload my config to the server"

AI: ✅ Uploaded config.json
    /app/config/config.json

---

You: "Download the error logs"

AI: ✅ Downloaded app.log
    Saved to ./logs/app.log

---

You: "Get database backup"

AI: ✅ Downloaded backup.sql
    (even through SSH jumps!)

It just works:

• ✅ Through any SSH session
• ✅ Multiple jump hosts
• ✅ Up to 10MB files
• ✅ Binary and text files

🎬 Real-World Example

Watch how a natural conversation becomes automated operations:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

👤 YOU ASK:
   "Debug the slow API on prod-server-01"

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🤖 AI EXECUTES:

   [Connecting...]
   → ssh user@prod-server-01
   ✅ Connected to prod-server-01

   [Investigating processes...]
   → ps aux | grep api
   📊 API process found: PID 1234, using 98% CPU

   [Checking logs...]
   → cd /var/log/api && tail -n 100 error.log
   🔍 ERROR: Memory leak in /api/v1/users endpoint

   [Downloading for analysis...]
   → Download: /var/log/api/error.log → ./local-debug/
   ✅ Downloaded 2.4MB (analyzed: 500+ memory errors)

   [Applying fix...]
   → Upload: ./fixed-config.yml → /app/config/
   ✅ Uploaded new rate-limiting config

   [Restarting service...]
   → systemctl restart api-service
   → systemctl status api-service
   ✅ Service restarted, CPU now at 12%

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🤖 AI RESPONDS:
   "Fixed! The API had a memory leak in the users endpoint.

   • Downloaded logs and found 500+ memory allocation errors
   • Applied rate-limiting configuration
   • Restarted service - CPU dropped from 98% to 12%
   • All operations completed in one persistent session"

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

✨ All in ONE session, NO re-authentication needed! ✨

📦 Installation

npm install -g mcp-shellkeeper

Configuration

Restart your AI assistant and you're ready! 🎉

💡 Use Cases

All through natural conversation with your AI! No scripts, no manual SSH juggling.

📖 Available Tools

The AI uses these tools automatically, but you can reference them for advanced use:

💡 Tip: The AI handles these automatically based on your natural language requests!

🔧 Technical Details

Persistent Sessions

• Uses PTY (Pseudo-Terminal) for full TTY emulation with state persistence
• Smart markers detect command completion automatically
• Exit codes captured for error detection
• Output parsed clean (no ANSI codes)

File Transfer

• Base64 encoding through existing SSH sessions (no separate SCP/SFTP)
• Works through jump hosts without re-authentication
• Max 10MB, 5-minute timeout (completes early if faster)

🐛 Troubleshooting

// Increase timeout for long-running commands
terminal_execute({
  command: "npm install",
  timeout: 120000  // 2 minutes
})

// Check if SSH keys are set up correctly
ssh -v user@server

# Set up passwordless authentication
ssh-keygen -t ed25519
ssh-copy-id user@server

# Verify
ssh user@server "echo Success"

// Check if in SSH session first
terminal_execute({ command: "pwd" })  // Verify you're on remote server

// Ensure remote directory exists
terminal_execute({ command: "mkdir -p /app/uploads" })

// Then upload
terminal_upload({ local_path: "file.txt", remote_path: "/app/uploads/file.txt" })

// Verify remote file exists
terminal_execute({ command: "ls -lh /path/to/file" })

// Check permissions
terminal_execute({ command: "cat /path/to/file | wc -l" })

// Try download with absolute path
terminal_download({ remote_path: "/full/path/to/file", local_path: "./" })

// List all sessions
terminal_list_sessions()

// Close problematic session
terminal_close_session({ session_id: "stuck-session" })

// Create fresh session
terminal_new_session({ session_id: "new-session" })

🧪 Development

# Clone repository
git clone https://github.com/tranhuucanh/mcp-shellkeeper.git
cd mcp-shellkeeper

# Install dependencies
npm install

# Build
npm run build

# Test locally with stdio transport
node dist/index.js

# Test with MCP Inspector
npm run inspector

🤝 Contributing

Contributions welcome! Help make AI-assisted server management better.

1. Fork the repository
2. Create feature branch (git checkout -b feature/amazing-feature)
3. Commit changes (git commit -m 'Add amazing feature')
4. Push to branch (git push origin feature/amazing-feature)
5. Open Pull Request

📄 License

MIT License - see LICENSE file for details.

You can:

• ✅ Use commercially
• ✅ Modify
• ✅ Distribute
• ✅ Private use

🙏 Acknowledgments

• Built with Model Context Protocol SDK
• Uses node-pty for terminal emulation
• Inspired by the need for stateful command execution in AI workflows

📞 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• MCP Community: Discord