mcp-ssh-server
Enables SSH connection to remote Linux servers for executing commands, reading/writing files, and managing directories via SFTP.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mcp-ssh-serverConnect to dev.example.com as admin"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
MCP SSH Server
A Model Context Protocol (MCP) server that bridges VS Code on Windows with remote Linux servers via SSH. This enables AI assistants like GitHub Copilot to seamlessly interact with remote development environments.
Features
π Password-to-Key Bootstrap: Connect once with a password, then automatically use SSH keys for all future connections
π Remote File System Access: Expose remote directories through MCP Resources
π οΈ Remote Command Execution: Run shell commands on remote servers with full stdout/stderr capture
π Direct File Operations: Read and write files directly to remote servers via SFTP
π Connection Management: Automatic reconnection and connection pooling
π Secure Key Storage: ED25519 keys stored locally in
~/.mcp-ssh/
Related MCP server: SSH MCP Server
Architecture
βββββββββββββββββββββββ
β VS Code + Copilot β
ββββββββββββ¬βββββββββββ
β stdio (MCP Protocol)
βΌ
βββββββββββββββββββββββ
β MCP SSH Server β
β βββββββββββββββββ β
β β Resource β β Exposes remote file system
β β Handler β β
β βββββββββββββββββ β
β βββββββββββββββββ β
β β Tool Handler β β Provides remote operations
β βββββββββββββββββ β
β βββββββββββββββββ β
β β SSH Manager β β Password-to-key bootstrap
β βββββββββββββββββ β
β βββββββββββββββββ β
β β SFTP Client β β File operations
β βββββββββββββββββ β
ββββββββββββ¬βββββββββββ
β SSH/SFTP
βΌ
βββββββββββββββββββββββ
β Remote Linux β
β Server β
βββββββββββββββββββββββInstallation
Clone the repository:
git clone <repository-url> mcp-ssh-server cd mcp-ssh-serverInstall dependencies:
npm installConfigure VS Code MCP Settings:
Add this configurationto to your MCP settings file. The location depends on your VS Code configuration:
{ "mcpServers": { "ssh-server": { "command": "node", "args": ["path\\mcp-ssh-server\\src\\index.js"], "env": { "LOG_LEVEL": "info" } } } }
Password-to-Key Bootstrap Flow
The MCP SSH Server implements an intelligent authentication flow:
First Connection
User provides SSH password
Server connects using password authentication
Server automatically generates an ED25519 key pair
Public key is deployed to
~/.ssh/authorized_keyson the remote serverPrivate key is stored in
~/.mcp-ssh/keys/id_ed25519_<host>Connection is re-established using the new key
Subsequent Connections
Server detects existing key for the host
Connects directly using key-based authentication
No password required!
Security Notes
Keys are stored with
0600permissions (owner read/write only)Each host gets a unique key pair
Keys are never transmitted after initial deployment
Password is only used once and not stored
Available Tools
The MCP server provides the following tools that can be invoked by AI assistants:
1. connect_ssh
Connect to a remote SSH server.
Parameters:
host(required): Remote host address or IPusername(required): SSH usernamepassword(optional): SSH password (only needed for first connection)port(optional): SSH port (default: 22)
Example:
{
"host": "example.com",
"username": "developer",
"password": "initial-password",
"port": 22
}2. execute_command
Execute a shell command on the remote server.
Parameters:
command(required): Shell command to executeworkingDirectory(optional): Working directory for the command
Example:
{
"command": "gcc main.c -o main && ./main",
"workingDirectory": "/home/developer/project"
}3. read_file
Read contents of a file from the remote server.
Parameters:
path(required): Absolute or relative path to the file
Example:
{
"path": "/home/developer/config.json"
}4. write_file
Write content to a file on the remote server.
Parameters:
path(required): Absolute or relative path to the filecontent(required): Content to write
Example:
{
"path": "/home/developer/script.sh",
"content": "#!/bin/bash\necho 'Hello World'"
}5. list_directory
List contents of a directory on the remote server.
Parameters:
path(optional): Directory path (defaults to home directory)
Example:
{
"path": "/home/developer/projects"
}VS Code Integration
Using with GitHub Copilot Chat
Once configured, you can interact with your remote server through Copilot:
Example prompts:
"Connect to my server at dev.example.com as user john"
"List files in the /var/www directory"
"Read the nginx configuration file"
"Compile and run the C++ program in ~/projects/app"
"Write this code to ~/app/server.js on the remote server"
Chat Variables (Future Enhancement)
To create a custom chat variable like @ssh-server, you would need to:
Create a VS Code extension that registers the chat participant
Use the MCP client library to communicate with this server
Register slash commands like
/connect,/exec,/read,/write
Example extension.js (conceptual):
vscode.chat.createChatParticipant(
"ssh-server",
async (request, context, stream, token) => {
// Connect to MCP server via stdio
// Forward user's request to appropriate tool
// Stream response back to chat
}
);Configuration
Environment Variables
LOG_LEVEL: Set logging level (debug,info,warn,error) - default:infoLOG_TO_FILE: Enable file logging - default:false
Directory Structure
~/.mcp-ssh/
βββ keys/ # SSH private keys
β βββ id_ed25519_user@host_22
β βββ id_ed25519_user@other_22
βββ config/ # Configuration files (future)
βββ logs/ # Log files (if enabled)Usage Examples
Example 1: Connect and Compile Code
User: "Connect to dev.example.com as developer with password 'mypass'"
AI: Uses connect_ssh tool
Server: Connects, generates keys, deploys public key
AI: "Connected! Future connections will use keys."
User: "Compile the C program in ~/project"
AI: Uses execute_command tool
Server: Executes "cd ~/project && gcc main.c -o main"
AI: Returns stdout/stderr and exit codeExample 2: Edit Remote Configuration
User: "Read the nginx config"
AI: Uses read_file tool with path "/etc/nginx/nginx.conf"
Server: Returns file contents
AI: Displays configuration
User: "Add this server block to the config..."
AI: Uses write_file tool
Server: Writes updated configuration
AI: "Configuration updated successfully"Troubleshooting
Connection Issues
Problem: "Connection timeout"
Check firewall rules on both Windows and Linux
Verify SSH service is running:
systemctl status sshdTest connection manually:
ssh user@host
Problem: "Key authentication failed"
Check
~/.ssh/authorized_keyspermissions on remote server (should be 600)Verify
~/.sshdirectory permissions (should be 700)Check server logs:
sudo tail -f /var/log/auth.log
Key Bootstrap Issues
Problem: "Failed to deploy public key"
Ensure user has write access to
~/.ssh/authorized_keysCheck if
~/.sshdirectory exists on remote serverVerify password authentication is enabled in
/etc/ssh/sshd_config
File Operation Issues
Problem: "Failed to write file"
Check file path permissions
Verify user has write access to the directory
Ensure parent directories exist
Development
Project Structure
mcp-ssh-server/
βββ src/
β βββ index.js # Entry point
β βββ config.js # Configuration
β βββ mcp/
β β βββ MCPServer.js # Main MCP server
β β βββ ResourceHandler.js # MCP Resources implementation
β β βββ ToolHandler.js # MCP Tools implementation
β βββ ssh/
β β βββ SSHConnectionManager.js # SSH connection management
β β βββ KeyManager.js # Key generation and deployment
β βββ sftp/
β β βββ SFTPClient.js # SFTP operations wrapper
β βββ utils/
β βββ logger.js # Logging utility
βββ package.json
βββ README.mdRunning in Development Mode
npm run devThis starts the server with Node.js inspector enabled for debugging.
Security Considerations
Key Storage: Private keys are stored in
~/.mcp-ssh/keys/with restrictive permissionsPassword Handling: Passwords are only used once and never stored
Connection Security: Uses modern SSH algorithms (ED25519, Curve25519)
File Operations: All file writes are atomic to prevent corruption
Logging: Passwords are redacted from logs
License
MIT
Contributing
Contributions are welcome! Please feel free to submit issues and pull requests.
Acknowledgments
Built with the Model Context Protocol SDK
Uses ssh2 for SSH connectivity
Uses ssh2-sftp-client for SFTP operations
Available Tools
5 toolsconnect_sshA
Connect to a remote SSH server. Use this first before any other operations.
| Name | Required | Description | Default |
|---|---|---|---|
| host | Yes | Remote host address or IP | |
| port | No | SSH port (default: 22) | |
| password | No | SSH password (only needed for first connection, will generate keys automatically) | |
| username | Yes | SSH username |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of disclosing behavior. It only restates the fact of connecting and gives a usage order; it does not mention session persistence, key generation, or other side effects that would be relevant for an SSH connection tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences that each serve a purpose: one states the function, the other gives ordering guidance. There is no wasted words or redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is minimal and does not explain the implications of establishing a connection (e.g., whether it persists for subsequent commands or what authentication flow occurs). However, the schema covers the password/key generation detail, and there is no output schema needed, so the description is not entirely incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for all parameters, so the schema already documents parameters. The tool description adds no additional parameter semantics beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: connecting to a remote SSH server. The phrase 'Use this first before any other operations' distinguishes it from the sibling operation tools by indicating it is a prerequisite step.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly instructs to use this tool before any other operations, providing a clear when-to-use guideline. It does not mention when not to use it or alternatives, but the sibling tools are operations that logically depend on this connection, so the guidance is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
execute_commandA
Execute a shell command on the remote server. Returns stdout, stderr, and exit code.
| Name | Required | Description | Default |
|---|---|---|---|
| command | Yes | The shell command to execute | |
| workingDirectory | No | Optional working directory (defaults to home directory) |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full responsibility for behavioral disclosure. It reveals that the tool returns stdout, stderr, and exit code, but omits important traits such as side effects (e.g., modifying system state), required permissions, or shell environment. For a command execution tool, this is a significant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is only two sentences, front-loaded with the tool's purpose and followed by return-value information. Every sentence contributes meaning, with no unnecessary fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no annotations or output schema, the description covers the primary function and return format, which is adequate for a simple two-parameter tool. However, it lacks safety caveats, usage boundaries relative to sibling tools, and any mention of environmental context, leaving it minimally complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the parameter descriptions in the schema (e.g., 'The shell command to execute') already provide clear meaning. The description adds no additional parameter details, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it executes a shell command on the remote server, using a specific verb+resource structure. It distinguishes itself from sibling tools like read_file, write_file, and connect_ssh by targeting arbitrary command execution.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies it should be used when a shell command needs to run, but it provides no explicit when-to-use or when-not-to-use guidance, and does not reference alternatives. Sibling tool context exists but is not leveraged in the description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_directoryA
List contents of a directory on the remote server
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | Absolute or relative path to the directory (defaults to home directory) |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure, but it only states the basic action. It does not mention whether listing is recursive, includes hidden files, what error occurs for invalid paths, or the output format. This is a sparse disclosure for a tool that will be used in scripted contexts.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence with no redundant words. It front-loads the action and resource, making it easy for an agent to parse quickly. Length is appropriate for the tool's simplicity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no annotations and no output schema, so the description must compensate by explaining what the tool returns and how it behaves in edge cases. It only says 'list contents' without specifying the response structure (e.g., file names only, metadata, sorting) or handling of errors like nonexistent directories. This leaves a significant gap for an agent to correctly interpret results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already documents the only parameter 'path' with a clear description including default behavior (home directory). Schema coverage is 100%, so the description does not need to add parameter details. Baseline of 3 applies because the schema handles the semantics effectively.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'List contents of a directory on the remote server' clearly specifies the action (list) and resource (directory contents) within a remote context. This distinguishes it from siblings like read_file (reads files) and write_file (writes files), making its purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear context for use: whenever directory contents need to be listed. It does not explicitly name alternatives or exclusion cases, but the siblings are visually distinct (execute_command, read_file, write_file, connect_ssh), so the tool's scope is evident. Lacks explicit 'when not to use' guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
read_fileA
Read the contents of a file from the remote server
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Absolute or relative path to the file |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden for behavioral disclosure. It correctly indicates a read-only operation ('Read the contents'), which is non-destructive, but it does not disclose error behavior, return format, or any limitations (e.g., binary files). This is minimally adequate but lacks depth.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that is front-loaded with the action and resource. Every word earns its place, with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter tool with a 100% schema, the description is mostly complete. It lacks an explicit statement about the return value (since there is no output schema), but 'Read the contents' implies the file data is returned. Adequate overall, though a note on encoding or error handling would improve it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (path described as 'Absolute or relative path to the file'), so the schema already documents the parameter. The description adds no additional meaning beyond what's in the schema, which is acceptable but not enhancing.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Read the contents') and the resource ('a file from the remote server'). It is distinct from sibling tools like write_file (write), list_directory (list), execute_command (execute), and connect_ssh (connect).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly indicates when to use this tool (for reading files) but does not explicitly state when not to use it or mention alternative tools. Sibling names like write_file suggest the contrast, but no explicit guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
write_fileB
Write content to a file on the remote server
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Absolute or relative path to the file | |
| content | Yes | Content to write to the file |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description must fully disclose behavioral traits. It does not state whether the file is overwritten, whether parent directories are created, or what permissions are needed. The only extra context is 'remote server', which adds minimal value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that directly states the tool's purpose. It has no unnecessary words or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with only 2 params and no output schema, but the description lacks details about overwrite behavior, return values, or creation of parent directories. It is minimally complete for a basic write operation but leaves some important questions unanswered.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents both parameters clearly. The description adds no additional parameter-specific meaning beyond the remote server context, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'write' and the resource 'content to a file on the remote server'. It is specific and distinguishes from siblings like read_file and list_directory by indicating a write operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. It does not mention prerequisites, exclusions, or comparison with sibling tools like execute_command or read_file.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
5 tool updates
v1.0.0- First observed
connect_ssh - First observed
execute_command - First observed
list_directory - First observed
read_file - First observed
write_file
TDQS
Each tool has a clearly distinct purpose: connect_ssh for establishing the connection, execute_command for running arbitrary commands, and read_file/write_file/list_directory for file system operations. There is no ambiguity between the tools, and their purposes are self-evident from their names.
All tool names follow a consistent verb_noun pattern in snake_case: connect_ssh, execute_command, read_file, write_file, list_directory. This makes the API predictable and easy to understand.
With five tools, the server is well-scoped and each tool serves a distinct, necessary function for SSH operations. The count falls within the ideal 3-15 range and does not feel either bloated or sparse.
The tool set covers essential SSH operations: connect, execute commands, read/write files, and list directories. While a disconnect tool or more advanced file operations (e.g., stat, upload) are missing, these can be worked around via execute_command, so the gaps are minor.
Maintenance
Resources
Unclaimed servers have limited discoverability.
Looking for Admin?
If you are the server author, to access and configure the admin panel.
Related MCP Connectors
Persistent memory and cross-session learning for AI coding assistants (hosted remote MCP).
Connect AI assistants to your GitHub-hosted Obsidian vault to seamlessly access, search, and analyβ¦
Connect AI assistants to GitHub - manage repos, issues, PRs, and workflows through natural language.
Live browser debugging for AI assistants β DOM, console, network via MCP.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceA bridge that enables AI assistants to connect to VS Code's debugger, allowing them to interact with and control debugging sessions through websocket connections.8MIT
- AlicenseAqualityDmaintenanceSSH MCP Server lets you manage remote Linux servers through natural language in VS Code Copilot Chat. Instead of switching to a terminal and remembering SSH commands23MIT

cygnus-ssh-mcpofficial
AlicenseAqualityBmaintenanceEnables AI assistants to manage remote servers via SSH with 43 specialized tools for command execution, file editing, directory operations, and background tasks across Linux, macOS, and Windows.445GPL 3.0- AlicenseBqualityDmaintenanceA Model Context Protocol (MCP) SSH client server that provides autonomous SSH operations for GitHub Copilot and VS Code. Enable natural language SSH automation without manual prompts or GUI interactions.201MIT
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/arieend/mcp-ssh-server'
If you have feedback or need assistance with the MCP directory API, please join our Discord server