README.mdโข5.84 kB
# SSH-PowerShell MCP Server
๐ **Enterprise-grade Model Context Protocol (MCP) server** for secure SSH and PowerShell command execution with Claude Desktop.
[](https://opensource.org/licenses/MIT)
[](https://nodejs.org/)
[](https://github.com/modelcontextprotocol/sdk)
## โจ Features
- ๏ฟฝ **Secure SSH command execution** on remote servers
- โก **Local PowerShell integration** for Windows automation
- ๐ก๏ธ **Enterprise security** with SSH key authentication
- ๐ **Network scanning** and SSH port discovery
- ๐ **SSH key verification** and host key scanning
- ๐ **Comprehensive logging** and error handling
- ๐ฏ **Claude Desktop optimized** for seamless AI integration
## ๏ฟฝ๐ Quick Start
```powershell
# Clone repository
git clone https://github.com/GUEPARD98/MCP-POWERSHELL.git
cd MCP-POWERSHELL
# Install dependencies
npm install
# Configure environment
Copy-Item config\.env.example config\.env
# Edit config\.env with your SSH settings
# Start server
npm start
```
## ๐ Project Structure
```
MCP-POWERSHELL/
โโโ ๐ config/ # Environment configurations
โ โโโ .env.example # Configuration template
โ โโโ .env.development # Development settings
โ โโโ .env.production # Production settings
โ โโโ .env.test # Test settings
โโโ ๐ docs/ # Complete documentation
โ โโโ README.md # Detailed guide
โ โโโ API.md # API reference
โ โโโ ARCHITECTURE.md # Technical architecture
โ โโโ SECURITY.md # Security best practices
โโโ ๐ scripts/ # PowerShell automation scripts
โ โโโ start.ps1 # Start server
โ โโโ stop.ps1 # Stop server
โ โโโ setup.ps1 # Initial setup
โ โโโ test.ps1 # Run tests
โโโ ๐ src/ # Source code
โ โโโ index.js # Main MCP server
โโโ ๐ tests/ # Automated tests
```
## ๐ ๏ธ Available Commands
| Command | Description |
|---------|-------------|
| `npm start` | Start MCP server |
| `npm test` | Run test suite |
| `npm run dev` | Development mode with PowerShell scripts |
| `npm run setup` | Initial configuration |
## โก MCP Tools
### ๐ ssh_execute
Execute commands on remote SSH servers
```javascript
// Example: Run 'ls -la' on remote server
{
"name": "ssh_execute",
"arguments": {
"command": "ls -la",
"host": "192.168.1.100",
"user": "root"
}
}
```
### ๐ป powershell_execute
Execute PowerShell commands locally
```javascript
// Example: Get Windows processes
{
"name": "powershell_execute",
"arguments": {
"command": "Get-Process | Select-Object -First 10"
}
}
```
### ๐ ssh_scan
Scan network for SSH services
```javascript
// Example: Scan local network
{
"name": "ssh_scan",
"arguments": {
"target": "192.168.1.0/24"
}
}
```
### ๐ ssh_keyscan
Verify SSH host keys
```javascript
// Example: Get host key fingerprint
{
"name": "ssh_keyscan",
"arguments": {
"host": "192.168.1.100"
}
}
```
## ๐ง Configuration
### Environment Setup
1. Copy `config/.env.example` to `config/.env`
2. Configure your SSH settings:
```properties
# SSH Configuration
SSH_KEY_PATH=/path/to/your/ssh/key
SSH_DEFAULT_HOST=your.server.ip
SSH_DEFAULT_USER=your_username
SSH_DEFAULT_PORT=22
# Security Settings
SSH_STRICT_HOST_KEY_CHECKING=no
COMMAND_TIMEOUT=30000
LOG_LEVEL=info
```
### Claude Desktop Integration
The server automatically configures Claude Desktop. Manual setup:
```json
{
"mcpServers": {
"ssh-powershell-mcp": {
"command": "node",
"args": ["path/to/MCP-POWERSHELL/src/index.js"],
"env": {
"NODE_ENV": "production"
}
}
}
}
```
## ๏ฟฝ Security
- โ
**SSH key authentication** only (no passwords)
- โ
**Command sanitization** with shell-escape
- โ
**Environment isolation** for different configurations
- โ
**Comprehensive input validation**
- โ
**Secure credential handling**
See [SECURITY.md](docs/SECURITY.md) for detailed security practices.
## ๐ Documentation
- **[Complete Guide](docs/README.md)** - Detailed installation and usage
- **[API Reference](docs/API.md)** - Full MCP API documentation
- **[Architecture](docs/ARCHITECTURE.md)** - Technical design and diagrams
- **[Security Guide](docs/SECURITY.md)** - Security best practices
## ๐งช Testing
```powershell
# Run all tests
npm test
# Run specific test types
.\scripts\test.ps1 -TestType unit
.\scripts\test.ps1 -TestType integration
.\scripts\test.ps1 -TestType ssh
```
## ๐ค Contributing
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
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## ๐โโ๏ธ Support
- ๐ Check the [documentation](docs/)
- ๐ Report issues on [GitHub Issues](https://github.com/GUEPARD98/MCP-POWERSHELL/issues)
- ๐ฌ Join discussions in [GitHub Discussions](https://github.com/GUEPARD98/MCP-POWERSHELL/discussions)
## ๐ Acknowledgments
- [Model Context Protocol](https://github.com/modelcontextprotocol) for the excellent SDK
- [Claude Desktop](https://claude.ai) for AI integration capabilities
- The open-source community for inspiration and tools
---
**๐ข Enterprise Ready** | **๐ Secure by Design** | **โก Claude Optimized**
Made with โค๏ธ by [GUEPARD98](https://github.com/GUEPARD98)