Skip to main content
Glama
Remote Terminal MCP Server

Remote Terminal MCP Server

by An-nima
README.md
# remote-terminal-mcp

一个提供远程终端能力的 MCP(Model Context Protocol)服务器。服务启动后会在本地标准输出生成一个随机 `Access Token`,后续所有调用必须在 HTTP 请求头携带 `Authorization: Bearer <token>`,否则统一返回 `401 Unauthorized`。

## 功能特性

- **启动自动生成并输出 Access Token**:使用加密随机数生成 256-bit Token(也支持通过 `MCP_ACCESS_TOKEN` 或 `--token` 指定)。
- **严格 HTTP 401 鉴权**:使用 `crypto.timingSafeEqual` 校验 Bearer Token,未认证或 Token 错误时返回 `401 Unauthorized` 与 `WWW-Authenticate: Bearer`。
- **Streamable HTTP MCP 传输**:基于 `@modelcontextprotocol/sdk` 在 `/mcp` 端点提供标准远程 MCP 服务。
- **终端工具集**:
  - `exec_command`:执行单次命令并返回 `stdout`、`stderr`、`exitCode`、耗时和超时状态。
  - `create_session`:创建持久化交互式 Shell 会话(保留工作目录和环境变量)。
  - `write_session`:向会话发送命令或输入文本。
  - `read_session`:按字节游标增量读取会话输出。
  - `list_sessions`:查看所有终端会话状态。
  - `close_session`:关闭并清理终端会话及子进程。

## 安装与运行

```bash
npm install
npm run build
npm start
```

启动后本地终端会输出:

```text
============================================================
Remote Terminal MCP Server started
MCP Endpoint : http://127.0.0.1:3000/mcp
Access Token : <your-generated-access-token>
Auth Header  : Authorization: Bearer <your-generated-access-token>
============================================================
```

### CLI 参数与环境变量

| 参数 | 环境变量 | 默认值 | 说明 |
| :--- | :--- | :--- | :--- |
| `--host <host>` | `HOST` | `127.0.0.1` | 监听地址 |
| `--port <port>` | `PORT` | `3000` | 监听端口 |
| `--token <token>` | `MCP_ACCESS_TOKEN` | 随机生成 | 固定 Access Token |

## 客户端配置示例

```json
{
  "mcpServers": {
    "remote-terminal": {
      "url": "http://127.0.0.1:3000/mcp",
      "headers": {
        "Authorization": "Bearer <your-generated-access-token>"
      }
    }
  }
}
```

## 测试

```bash
npm run build
npm test
```