# MobaXterm MCP Server

[中文文档](README_zh.md) | English

An MCP (Model Context Protocol) Server that enables AI agents to interact with [MobaXterm](https://mobaxterm.mobatek.net/) — manage SSH sessions, execute remote commands, transfer files via SFTP, and monitor terminal activity.

## Features

### Session Management
- **list_sessions** — List all saved sessions from MobaXterm.ini (supports bookmarks, folders, and multiple bookmark sections)
- **get_session_detail** — Get detailed configuration of a specific session (host, port, protocol, username, etc.)

### SSH Connection & Command Execution
- **ssh_connect** — Establish SSH connections (password or key-based auth), with optional connection reuse from saved sessions
- **ssh_exec** — Execute commands on connected servers with stdout/stderr/exit code output
- **ssh_disconnect** — Gracefully disconnect SSH sessions
- **ssh_list_connections** — List all active SSH connections

### SFTP File Transfer
- **sftp_list** — List remote directory contents with file metadata (size, permissions, owner, modified time)
- **sftp_upload** — Upload local files to remote servers
- **sftp_download** — Download remote files to local machine
- **sftp_mkdir** — Create remote directories (recursive)
- **sftp_delete** — Delete remote files or directories
- **sftp_stat** — Get detailed file information (size, permissions, timestamps)

### Terminal Log Monitoring
- **monitor_start** — Start real-time monitoring of a MobaXterm session's terminal output
- **monitor_stop** — Stop monitoring
- **monitor_get_recent** — Retrieve recent terminal activity (with configurable time window)
- **monitor_list_logs** — List all available MobaXterm log files
- **monitor_search** — Search keywords in session logs

## Quick Start

### Prerequisites

- **Node.js** v18 or higher
- **MobaXterm** (Portable or Installer edition)

### Installation

```bash
git clone https://github.com/bobzzgm/mobaxterm-mcp.git
cd mobaxterm-mcp
npm install
npm run build
```

### Configuration

The MCP server requires the path to your `MobaXterm.ini` file:

- **Portable edition**: `MobaXterm.ini` is in the same directory as `MobaXterm.exe`
- **Installer edition**: Usually at `C:\Users\<User>\AppData\Roaming\MobaXterm\MobaXterm.ini`

## Usage with AI Tools

### Qoder

Add to your workspace `.mcp.json`:

```json
{
  "mcpServers": {
    "mobaxterm": {
      "command": "node",
      "args": [
        "/path/to/mobaxterm-mcp/dist/index.js",
        "--iniPath",
        "/path/to/MobaXterm.ini"
      ]
    }
  }
}
```

### Claude Desktop

Edit `%APPDATA%\Claude\claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "mobaxterm": {
      "command": "node",
      "args": [
        "/path/to/mobaxterm-mcp/dist/index.js",
        "--iniPath",
        "/path/to/MobaXterm.ini"
      ]
    }
  }
}
```

### Cursor

Create `.cursor/mcp.json` in your project root:

```json
{
  "mcpServers": {
    "mobaxterm": {
      "command": "node",
      "args": [
        "/path/to/mobaxterm-mcp/dist/index.js",
        "--iniPath",
        "/path/to/MobaXterm.ini"
      ]
    }
  }
}
```

### Windsurf

Edit `~/.codeium/windsurf/mcp_config.json`:

```json
{
  "mcpServers": {
    "mobaxterm": {
      "command": "node",
      "args": [
        "/path/to/mobaxterm-mcp/dist/index.js",
        "--iniPath",
        "/path/to/MobaXterm.ini"
      ]
    }
  }
}
```

## Command Line Options

| Option | Description | Default |
|--------|-------------|---------|
| `--iniPath <path>` | Path to MobaXterm.ini | **Required** |
| `--logDir <path>` | Path to MobaXterm log directory | Auto-detected from iniPath |
| `--timeout <ms>` | SSH connection timeout in milliseconds | 60000 |

## Architecture

```
mobaxterm-mcp/
├── src/
│   ├── index.ts              # Entry point - MCP Server setup
│   ├── types/
│   │   └── index.ts          # TypeScript type definitions
│   ├── services/
│   │   ├── ini-parser.ts     # MobaXterm INI parser (GBK/UTF-8)
│   │   ├── ssh-manager.ts    # SSH connection pool (ssh2)
│   │   ├── sftp-manager.ts   # SFTP operations (ssh2-sftp-client)
│   │   └── log-watcher.ts    # Real-time log monitoring (chokidar)
│   └── tools/
│       ├── session-tools.ts  # Session management tools
│       ├── ssh-tools.ts      # SSH tools
│       ├── sftp-tools.ts     # SFTP tools
│       └── monitor-tools.ts  # Monitoring tools
├── package.json
├── tsconfig.json
└── README.md
```

### Key Technical Details

- **INI Parser**: Custom parser that handles MobaXterm's special INI format (values prefixed with `#CODE#` protocol identifiers, `%`-delimited fields). Supports GBK (cp936) encoding for Chinese folder/bookmark names via `iconv-lite`.
- **Protocol Detection**: Parses MobaXterm protocol codes (SSH=109, Telnet=98, WSL=105, Serial=131, RDP=1, VNC=2).
- **Multi-Bookmark Sections**: Supports `[Bookmarks]`, `[Bookmarks_1]`, `[Bookmarks_2]`, etc.
- **Log File Matching**: Auto-discovers MobaXterm log files by session name from the configured log directory.

## Development

```bash
# Build
npm run build

# Watch mode for development
npm run dev

# Inspect with MCP Inspector
npm run inspect
```

## License

MIT