ShellKeeper

ShellKeeper turns AI assistants into stateful operators by providing persistent SSH sessions and seamless file transfer, enabling you to run commands, manage files, and maintain context across interactions without re-authenticating for every operation.

How to use

Begin by installing ShellKeeper globally and then configuring your MCP client to load the ShellKeeper MCP server. Once set up, you can use natural language prompts to connect to servers, run commands, transfer files, and explore remote environments with full session context.

How to install

npm install -g mcp-shellkeeper

# Verify installation
shellkeeper --version

# Basic startup example (when used through an MCP client) depends on your client configuration
# The following shows how you reference the server in your client settings

Configuration snippet for your MCP client

{
  "mcpServers": {
    "shellkeeper": {
      "command": "npx",
      "args": ["-y", "mcp-shellkeeper"]
    }
  }
}

Place this in the appropriate client settings file (for Cursor, Claude, or VS Code integration) as shown by your client’s configuration flow.

## Configuration and usage notes

ShellKeeper supports a single, explicit MCP server configuration in the available examples. The standard runtime command is `npx` with arguments `-y` and `mcp-shellkeeper`, which executes the ShellKeeper MCP server locally and exposes it to your MCP client.

If you want to enable multiple clients or environments, you can reference the same stdio configuration under different client profiles, but do not omit the required arguments when configuring each profile.

## Security and best practices

- Use SSH keys for authentication and avoid passwords in scripts.
- Prefer jump hosts for production access to reduce exposure.
- Limit remote upload destinations to safe directories and monitor sessions.
- Clean up sessions after tasks complete and audit all operations.

## Troubleshooting

If commands time out or sessions become unresponsive, verify that your MCP client is correctly loading the ShellKeeper server configuration and that the underlying Node environment is installed and reachable.

## Available tools and capabilities

ShellKeeper exposes a set of terminal and session management tools that you use through natural language prompts. Key capabilities include executing commands in a persistent session, uploading and downloading files, starting new sessions, listing active sessions, closing sessions, and debugging raw terminal output.

## Available tools

### terminal\_execute

Run commands inside a persistent SSH session with output capture, exit codes, and timeout handling.

### terminal\_upload\_file

Upload local files to the remote server through an existing SSH session, up to 10MB with automatic path handling.

### terminal\_download\_file

Download files from the remote server to your local machine through the persistent session, preserving structure and permissions.

### terminal\_new\_session

Create a new isolated persistent session for parallel operations or separate environments.

### terminal\_list\_sessions

List all active sessions with status and uptime to help you manage multiple connections.

### terminal\_close\_session

Close a specific session to free resources when tasks finish or become problematic.

### terminal\_get\_buffer

Fetch raw terminal output for troubleshooting and debugging.