From 1270ac749e5c68a6a4fbc8b0c7385d167712647d Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Tue, 23 Dec 2025 04:56:41 +0000 Subject: [PATCH 1/4] Refactor client setup and configuration documentation Co-authored-by: zhouhua258 --- README.md | 185 +++++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 162 insertions(+), 23 deletions(-) diff --git a/README.md b/README.md index 03fe852..f382c67 100644 --- a/README.md +++ b/README.md @@ -28,6 +28,8 @@ pip install remoteshell-mcp uv pip install remoteshell-mcp ``` +After installation, proceed to the [Client Setup](#client-setup) section to configure your MCP client. + ### Option 2: Install from Source #### Prerequisites @@ -48,6 +50,8 @@ uv sync # The server is now ready to use ``` +After installation, proceed to the [Client Setup](#client-setup) section to configure your MCP client. When using source installation, use the "Option B: Using uv run" configuration method. + ## Configuration There are three ways to configure SSH connections: @@ -86,7 +90,7 @@ chmod 600 ~/.remoteShell/config.json ### 2. MCP Client Configuration (Recommended for Claude Code/Cursor) -Configure connections directly in your MCP client settings (see below for specific examples). +Configure connections directly in your MCP client settings. You can pass connections as inline JSON or reference a config file path. See the [Client Setup](#client-setup) section below for detailed examples. ### 3. Dynamic Creation @@ -94,40 +98,107 @@ Create connections on-the-fly using the `create_connection` tool during a conver ## Client Setup -### Claude Code Configuration +After installing the package (via pip or uv), configure your MCP client to use the server. The configuration method depends on how you installed the package. + +### Quick Setup (Recommended) + +#### Option A: Using pip/uv installed package (Recommended) -Add the following to your Claude Code MCP settings file (usually located at `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS): +If you installed via `pip install remoteshell-mcp` or `uv pip install remoteshell-mcp`, use the direct command: + +**Claude Code Configuration** + +Add to your Claude Code MCP settings file (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS, or `%APPDATA%\Claude\claude_desktop_config.json` on Windows): + +**Basic Configuration (no pre-configured connections):** ```json { "mcpServers": { "remoteshell": { - "command": "uv", + "type": "stdio", + "command": "remoteshell-mcp" + } + } +} +``` + +**Note**: If the above doesn't work in your environment, try adding the command name as the first argument: +```json +{ + "mcpServers": { + "remoteshell": { + "type": "stdio", + "command": "remoteshell-mcp", + "args": ["remoteshell-mcp"] + } + } +} +``` + +**With Pre-configured Connections (Inline JSON):** + +```json +{ + "mcpServers": { + "remoteshell": { + "type": "stdio", + "command": "remoteshell-mcp", "args": [ - "--directory", - "/absolute/path/to/remoteShell-mcp", - "run", - "remoteshell-mcp" + "remoteshell-mcp", + "--connections", + "[{\"id\":\"server1\",\"host\":\"192.168.1.100\",\"user\":\"admin\",\"auth_type\":\"password\",\"password\":\"your_password\"}]" ] } } } ``` -#### With Pre-configured Connections: +**With Pre-configured Connections (Config File):** ```json { "mcpServers": { "remoteshell": { - "command": "uv", + "type": "stdio", + "command": "remoteshell-mcp", + "args": [ + "remoteshell-mcp", + "--connections", + "~/.remoteShell/config.json" + ] + } + } +} +``` + +**Cursor Configuration** + +Add to your Cursor settings (Settings → Features → MCP): + +```json +{ + "mcpServers": { + "remoteshell": { + "type": "stdio", + "command": "remoteshell-mcp" + } + } +} +``` + +**With Pre-configured Connections:** + +```json +{ + "mcpServers": { + "remoteshell": { + "type": "stdio", + "command": "remoteshell-mcp", "args": [ - "--directory", - "/absolute/path/to/remoteShell-mcp", - "run", "remoteshell-mcp", "--connections", - "[{\"id\":\"server1\",\"host\":\"192.168.1.100\",\"user\":\"admin\",\"auth_type\":\"password\",\"password\":\"secret\"}]" + "[{\"id\":\"server1\",\"host\":\"192.168.1.100\",\"user\":\"admin\",\"auth_type\":\"password\",\"password\":\"your_password\"}]" ] } } @@ -140,23 +211,23 @@ Or reference a configuration file: { "mcpServers": { "remoteshell": { - "command": "uv", + "type": "stdio", + "command": "remoteshell-mcp", "args": [ - "--directory", - "/absolute/path/to/remoteShell-mcp", - "run", "remoteshell-mcp", "--connections", - "/path/to/your/connections.json" + "~/.remoteShell/config.json" ] } } } ``` -### Cursor Configuration +#### Option B: Using uv run (for development or when package is not globally installed) + +If you cloned the repository and want to run from source: -Add the following to your Cursor settings (Settings → Features → MCP): +**Claude Code Configuration:** ```json { @@ -174,7 +245,7 @@ Add the following to your Cursor settings (Settings → Features → MCP): } ``` -#### With Pre-configured Connections: +**With Pre-configured Connections:** ```json { @@ -187,7 +258,25 @@ Add the following to your Cursor settings (Settings → Features → MCP): "run", "remoteshell-mcp", "--connections", - "/path/to/your/connections.json" + "[{\"id\":\"server1\",\"host\":\"192.168.1.100\",\"user\":\"admin\",\"auth_type\":\"password\",\"password\":\"your_password\"}]" + ] + } + } +} +``` + +**Cursor Configuration:** + +```json +{ + "mcpServers": { + "remoteshell": { + "command": "uv", + "args": [ + "--directory", + "/absolute/path/to/remoteShell-mcp", + "run", + "remoteshell-mcp" ] } } @@ -196,6 +285,56 @@ Add the following to your Cursor settings (Settings → Features → MCP): **Note**: Replace `/absolute/path/to/remoteShell-mcp` with the actual absolute path to this repository on your system. +### Connection Configuration Examples + +**Password Authentication:** +```json +{ + "id": "prod-server", + "host": "192.168.1.100", + "port": 22, + "user": "admin", + "auth_type": "password", + "password": "your_password" +} +``` + +**SSH Key Authentication:** +```json +{ + "id": "dev-server", + "host": "192.168.1.101", + "port": 22, + "user": "developer", + "auth_type": "key", + "key_path": "~/.ssh/id_rsa" +} +``` + +**Multiple Connections (for config file):** +```json +{ + "connections": [ + { + "id": "prod-server", + "host": "192.168.1.100", + "port": 22, + "user": "admin", + "auth_type": "password", + "password": "your_password" + }, + { + "id": "dev-server", + "host": "192.168.1.101", + "port": 22, + "user": "developer", + "auth_type": "key", + "key_path": "~/.ssh/id_rsa" + } + ] +} +``` + ## Available Tools ### 1. `create_connection` From b577e8f3671e8b70065c2a09014629d54bb78e3c Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Tue, 23 Dec 2025 07:01:17 +0000 Subject: [PATCH 2/4] Refactor README to include uvx installation and simplify client setup Co-authored-by: zhouhua258 --- README.md | 149 ++++++++++++++++++++++++------------------------------ 1 file changed, 66 insertions(+), 83 deletions(-) diff --git a/README.md b/README.md index f382c67..97f9402 100644 --- a/README.md +++ b/README.md @@ -30,7 +30,18 @@ uv pip install remoteshell-mcp After installation, proceed to the [Client Setup](#client-setup) section to configure your MCP client. -### Option 2: Install from Source +### Option 2: Use uvx (No Installation Required) + +You can run the server directly without installing it globally using `uvx`: + +```bash +# No installation needed, uvx will download and run it automatically +uvx remoteshell-mcp +``` + +When configuring your MCP client, use `uvx` as the command (see [Client Setup](#client-setup) section). + +### Option 3: Install from Source #### Prerequisites @@ -50,7 +61,7 @@ uv sync # The server is now ready to use ``` -After installation, proceed to the [Client Setup](#client-setup) section to configure your MCP client. When using source installation, use the "Option B: Using uv run" configuration method. +After installation, proceed to the [Client Setup](#client-setup) section to configure your MCP client. ## Configuration @@ -98,17 +109,23 @@ Create connections on-the-fly using the `create_connection` tool during a conver ## Client Setup -After installing the package (via pip or uv), configure your MCP client to use the server. The configuration method depends on how you installed the package. +After installing the package via `pip install remoteshell-mcp`, configure your MCP client to use the server. + +### Claude Code Configuration + +#### Quick Setup with `claude mcp add` Command (Recommended) -### Quick Setup (Recommended) +The easiest way to add this MCP server to Claude Code is using the `claude mcp add` command: -#### Option A: Using pip/uv installed package (Recommended) +```bash +claude mcp add remoteshell remoteshell-mcp +``` -If you installed via `pip install remoteshell-mcp` or `uv pip install remoteshell-mcp`, use the direct command: +This will automatically add the server to your Claude Code configuration. If you need to add pre-configured connections, you can manually edit the configuration file afterward. -**Claude Code Configuration** +#### Manual Configuration -Add to your Claude Code MCP settings file (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS, or `%APPDATA%\Claude\claude_desktop_config.json` on Windows): +Alternatively, you can manually add the following to your Claude Code MCP settings file (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS, or `%APPDATA%\Claude\claude_desktop_config.json` on Windows): **Basic Configuration (no pre-configured connections):** @@ -172,29 +189,16 @@ Add to your Claude Code MCP settings file (`~/Library/Application Support/Claude } ``` -**Cursor Configuration** +#### Using uvx (without installing the package) -Add to your Cursor settings (Settings → Features → MCP): +If you prefer to run without installing the package globally, you can use `uvx`: ```json { "mcpServers": { "remoteshell": { "type": "stdio", - "command": "remoteshell-mcp" - } - } -} -``` - -**With Pre-configured Connections:** - -```json -{ - "mcpServers": { - "remoteshell": { - "type": "stdio", - "command": "remoteshell-mcp", + "command": "uvx", "args": [ "remoteshell-mcp", "--connections", @@ -212,7 +216,7 @@ Or reference a configuration file: "mcpServers": { "remoteshell": { "type": "stdio", - "command": "remoteshell-mcp", + "command": "uvx", "args": [ "remoteshell-mcp", "--connections", @@ -223,23 +227,18 @@ Or reference a configuration file: } ``` -#### Option B: Using uv run (for development or when package is not globally installed) +### Cursor Configuration -If you cloned the repository and want to run from source: +Add to your Cursor settings (Settings → Features → MCP): -**Claude Code Configuration:** +**Basic Configuration:** ```json { "mcpServers": { "remoteshell": { - "command": "uv", - "args": [ - "--directory", - "/absolute/path/to/remoteShell-mcp", - "run", - "remoteshell-mcp" - ] + "type": "stdio", + "command": "remoteshell-mcp" } } } @@ -251,11 +250,9 @@ If you cloned the repository and want to run from source: { "mcpServers": { "remoteshell": { - "command": "uv", + "type": "stdio", + "command": "remoteshell-mcp", "args": [ - "--directory", - "/absolute/path/to/remoteShell-mcp", - "run", "remoteshell-mcp", "--connections", "[{\"id\":\"server1\",\"host\":\"192.168.1.100\",\"user\":\"admin\",\"auth_type\":\"password\",\"password\":\"your_password\"}]" @@ -265,73 +262,59 @@ If you cloned the repository and want to run from source: } ``` -**Cursor Configuration:** +Or reference a configuration file: ```json { "mcpServers": { "remoteshell": { - "command": "uv", + "type": "stdio", + "command": "remoteshell-mcp", "args": [ - "--directory", - "/absolute/path/to/remoteShell-mcp", - "run", - "remoteshell-mcp" + "remoteshell-mcp", + "--connections", + "~/.remoteShell/config.json" ] } } } ``` -**Note**: Replace `/absolute/path/to/remoteShell-mcp` with the actual absolute path to this repository on your system. +#### Using uvx (without installing the package) -### Connection Configuration Examples +If you prefer to run without installing the package globally, you can use `uvx`: -**Password Authentication:** ```json { - "id": "prod-server", - "host": "192.168.1.100", - "port": 22, - "user": "admin", - "auth_type": "password", - "password": "your_password" + "mcpServers": { + "remoteshell": { + "type": "stdio", + "command": "uvx", + "args": [ + "remoteshell-mcp", + "--connections", + "[{\"id\":\"server1\",\"host\":\"192.168.1.100\",\"user\":\"admin\",\"auth_type\":\"password\",\"password\":\"your_password\"}]" + ] + } + } } ``` -**SSH Key Authentication:** -```json -{ - "id": "dev-server", - "host": "192.168.1.101", - "port": 22, - "user": "developer", - "auth_type": "key", - "key_path": "~/.ssh/id_rsa" -} -``` +Or reference a configuration file: -**Multiple Connections (for config file):** ```json { - "connections": [ - { - "id": "prod-server", - "host": "192.168.1.100", - "port": 22, - "user": "admin", - "auth_type": "password", - "password": "your_password" - }, - { - "id": "dev-server", - "host": "192.168.1.101", - "port": 22, - "user": "developer", - "auth_type": "key", - "key_path": "~/.ssh/id_rsa" + "mcpServers": { + "remoteshell": { + "type": "stdio", + "command": "uvx", + "args": [ + "remoteshell-mcp", + "--connections", + "~/.remoteShell/config.json" + ] } - ] + } } ``` From c2c3b720d7f0a2cced0346dd13102d14a5abbf62 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Tue, 23 Dec 2025 07:32:04 +0000 Subject: [PATCH 3/4] Refactor installation and client setup instructions Co-authored-by: zhouhua258 --- README.md | 186 ++++-------------------------------------------------- 1 file changed, 12 insertions(+), 174 deletions(-) diff --git a/README.md b/README.md index 97f9402..a16f564 100644 --- a/README.md +++ b/README.md @@ -18,51 +18,20 @@ A Model Context Protocol (MCP) server that enables AI models to manage SSH conne ## Installation -### Option 1: Install from PyPI (Recommended) +### Option 1: Use uvx (Recommended) -```bash -# Install with pip -pip install remoteshell-mcp - -# Or install with uv -uv pip install remoteshell-mcp -``` - -After installation, proceed to the [Client Setup](#client-setup) section to configure your MCP client. - -### Option 2: Use uvx (No Installation Required) - -You can run the server directly without installing it globally using `uvx`: +No installation required. `uvx` will download and run the server automatically: ```bash -# No installation needed, uvx will download and run it automatically uvx remoteshell-mcp ``` -When configuring your MCP client, use `uvx` as the command (see [Client Setup](#client-setup) section). - -### Option 3: Install from Source - -#### Prerequisites - -- Python 3.11 or higher -- [uv](https://github.com/astral-sh/uv) package manager - -#### Steps +### Option 2: Install from PyPI ```bash -# Clone the repository -git clone https://github.com/chouzz/remoteShell-mcp.git -cd remoteShell-mcp - -# Install dependencies -uv sync - -# The server is now ready to use +pip install remoteshell-mcp ``` -After installation, proceed to the [Client Setup](#client-setup) section to configure your MCP client. - ## Configuration There are three ways to configure SSH connections: @@ -101,97 +70,17 @@ chmod 600 ~/.remoteShell/config.json ### 2. MCP Client Configuration (Recommended for Claude Code/Cursor) -Configure connections directly in your MCP client settings. You can pass connections as inline JSON or reference a config file path. See the [Client Setup](#client-setup) section below for detailed examples. +Configure connections directly in your MCP client settings. You can pass connections as inline JSON or reference a config file path. -### 3. Dynamic Creation - -Create connections on-the-fly using the `create_connection` tool during a conversation with your AI assistant. - -## Client Setup - -After installing the package via `pip install remoteshell-mcp`, configure your MCP client to use the server. - -### Claude Code Configuration - -#### Quick Setup with `claude mcp add` Command (Recommended) - -The easiest way to add this MCP server to Claude Code is using the `claude mcp add` command: +**Quick Setup for Claude Code:** ```bash -claude mcp add remoteshell remoteshell-mcp -``` - -This will automatically add the server to your Claude Code configuration. If you need to add pre-configured connections, you can manually edit the configuration file afterward. - -#### Manual Configuration - -Alternatively, you can manually add the following to your Claude Code MCP settings file (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS, or `%APPDATA%\Claude\claude_desktop_config.json` on Windows): - -**Basic Configuration (no pre-configured connections):** - -```json -{ - "mcpServers": { - "remoteshell": { - "type": "stdio", - "command": "remoteshell-mcp" - } - } -} +claude mcp add --transport stdio remoteshell -- remoteshell-mcp ``` -**Note**: If the above doesn't work in your environment, try adding the command name as the first argument: -```json -{ - "mcpServers": { - "remoteshell": { - "type": "stdio", - "command": "remoteshell-mcp", - "args": ["remoteshell-mcp"] - } - } -} -``` +**Example Configurations:** -**With Pre-configured Connections (Inline JSON):** - -```json -{ - "mcpServers": { - "remoteshell": { - "type": "stdio", - "command": "remoteshell-mcp", - "args": [ - "remoteshell-mcp", - "--connections", - "[{\"id\":\"server1\",\"host\":\"192.168.1.100\",\"user\":\"admin\",\"auth_type\":\"password\",\"password\":\"your_password\"}]" - ] - } - } -} -``` - -**With Pre-configured Connections (Config File):** - -```json -{ - "mcpServers": { - "remoteshell": { - "type": "stdio", - "command": "remoteshell-mcp", - "args": [ - "remoteshell-mcp", - "--connections", - "~/.remoteShell/config.json" - ] - } - } -} -``` - -#### Using uvx (without installing the package) - -If you prefer to run without installing the package globally, you can use `uvx`: +**Using uvx (no installation required):** ```json { @@ -227,24 +116,7 @@ Or reference a configuration file: } ``` -### Cursor Configuration - -Add to your Cursor settings (Settings → Features → MCP): - -**Basic Configuration:** - -```json -{ - "mcpServers": { - "remoteshell": { - "type": "stdio", - "command": "remoteshell-mcp" - } - } -} -``` - -**With Pre-configured Connections:** +**Using remoteshell-mcp (after pip install):** ```json { @@ -280,43 +152,9 @@ Or reference a configuration file: } ``` -#### Using uvx (without installing the package) - -If you prefer to run without installing the package globally, you can use `uvx`: - -```json -{ - "mcpServers": { - "remoteshell": { - "type": "stdio", - "command": "uvx", - "args": [ - "remoteshell-mcp", - "--connections", - "[{\"id\":\"server1\",\"host\":\"192.168.1.100\",\"user\":\"admin\",\"auth_type\":\"password\",\"password\":\"your_password\"}]" - ] - } - } -} -``` - -Or reference a configuration file: +### 3. Dynamic Creation -```json -{ - "mcpServers": { - "remoteshell": { - "type": "stdio", - "command": "uvx", - "args": [ - "remoteshell-mcp", - "--connections", - "~/.remoteShell/config.json" - ] - } - } -} -``` +Create connections on-the-fly using the `create_connection` tool during a conversation with your AI assistant. ## Available Tools From 0c1a607e2d799ec5b047ef12db4412276f137b87 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Tue, 23 Dec 2025 07:46:25 +0000 Subject: [PATCH 4/4] Refactor: Improve MCP connection configuration in README Co-authored-by: zhouhua258 --- README.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index a16f564..1e28710 100644 --- a/README.md +++ b/README.md @@ -75,7 +75,13 @@ Configure connections directly in your MCP client settings. You can pass connect **Quick Setup for Claude Code:** ```bash -claude mcp add --transport stdio remoteshell -- remoteshell-mcp +claude mcp add --transport stdio remoteshell -- remoteshell-mcp --connections "[{\"id\":\"server1\",\"host\":\"192.168.1.100\",\"user\":\"admin\",\"auth_type\":\"password\",\"password\":\"your_password\"}]" +``` + +Or reference a configuration file: + +```bash +claude mcp add --transport stdio remoteshell -- remoteshell-mcp --connections "~/.remoteShell/config.json" ``` **Example Configurations:** @@ -152,10 +158,6 @@ Or reference a configuration file: } ``` -### 3. Dynamic Creation - -Create connections on-the-fly using the `create_connection` tool during a conversation with your AI assistant. - ## Available Tools ### 1. `create_connection`