Local Ssh MCP

MCP开发工具

提供方 terria1020

开发工具 未标注 OAuth 授权 社区 / 第三方 Claude

一个基于Node.js和TypeScript的本地SSH MCP服务器,用于安全地执行远程SSH命令并通过Claude Code进行管理。

一句话选型结论

按资料字段整理

Local Ssh MCP 属于开发工具类 MCP 服务器,传输方式未标注,OAuth 授权,可直接接入 Claude,没有现成安装命令,需按官方文档接入。接入前先确认权限范围;涉及写入、删除或付款的操作,建议先在测试环境验证。

分类开发工具 传输方式未标注 鉴权OAuth 授权 部署方式未标注
GitHub 星标 1 仓库热度,无公开仓库时显示未标注
工具数 3 暴露给模型的工具数量
资源 / 提示词 0 / 0 资源与提示词模板数量
维护方 社区 / 第三方 核验等级 仅资料核对

工具与能力

开发工具
数量来自来源目录的标注,具体工具清单以官方文档为准
工具数量3暴露给模型可调用的工具个数
资源数量0可读取的资源条目
提示词数量0内置提示词模板数量

能力标签

支持客户端

适用场景

SSH管理TypeScript本地部署远程命令执行安全协议开发工具Node.js

安装与配置

未标注 OAuth 授权
上游未给出传输方式
  1. 1
    准备运行环境

    按官方文档确认运行环境(常见为 Node.js 或 Python),装好后再执行安装命令。

  2. 2
    安装服务

    复制上面的安装命令执行;命令里带占位符的位置,换成自己的密钥或路径。

  3. 3
    写入客户端配置

    在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,让新配置生效。

  4. 4
    验证是否可用

    连接成功后客户端会列出约 3 个工具,随便调一个只读工具确认能返回结果。

典型使用场景

3 类
按分类与标签整理的常见用法,具体以官方文档为准
代码与仓库操作

在对话里直接查代码、提 issue、走 PR,省掉来回切工具。

本地命令与脚本

把构建、测试、格式化这类重复命令交给模型执行。

接口联调与测试

让模型调你的接口、跑一遍用例,快速定位问题。

选择建议

选之前先看这几条
按条目字段给出的判断,不替你决定用不用

值得选的地方

  • 资料标注 3 个工具,职责相对集中,接入后不容易误操作。
  • 已适配 Claude,换客户端不用重新研究配置。

先想清楚的地方

  • 没有现成安装命令,需要按官方文档自己填启动命令和参数。
  • 使用前要准备好OAuth 授权对应的凭据,并按最小权限配置。
  • 版本更新与行为细节以官方仓库为准。

更适合

  • 需要在开发工具场景里让模型直接调用外部能力的人。
  • 已经在用 Claude 的用户,接入路径最短。
  • 想先快速试一下、能接受在本地或自有环境跑服务的人。

不太适合

  • 不方便管理密钥或第三方授权的人。
  • 需要厂商级 SLA 和技术支持的生产环境。

同类对比

6 个同类
同分类里挑最接近的几条,字段以各自详情页为准
MCP 服务器工具数传输方式部署方式安装命令最后核验
Local Ssh MCP当前 3 未标注 未标注 无 2026-05-17
Git 838e2ec1 12 stdio · 本地进程 本地部署 有 2026-05-17
Markitdown MCP 2c653a5f 1 stdio · 本地进程 本地部署 有 2026-05-17
JavaGuide 未标注 stdio · 本地进程 本地部署 有 2026-04-11
awesome-claude-skills 未标注 stdio · 本地进程 本地部署 有 2026-04-26
Context7 831acf40 未标注 stdio · 本地进程 本地部署 有 2026-05-17

服务器档案

开发工具
字段来自项目仓库与公开索引,中文说明由本站标注
提供方terria1020上游标注的维护方 terria1020
分类开发工具本站按上游分类展示
连接方式未标注上游未给出传输方式
鉴权方式OAuth 授权远程服务建议用最小权限凭据
维护方社区 / 第三方核验等级 仅资料核对
包名 / 运行时未标注 · 未标注本地安装时用到的包标识与运行时
部署类型未标注上游给出的部署形态
最近核验2026-05-17上游最后核验时间

详细介绍

14.8 KB
来自项目仓库与上游目录的原文,未做删改

本地SSH MCP服务器

用于Claude Code的安全本地SSH MCP服务器

Node.js+基于TypeScript的模型上下文协议(MCP)服务器。Claude Code允许通过SSH连接到远程服务器并运行命令,但SSH身份验证信息仅在本地环境中管理,以防止外部暴露。

版本:3.1.0(带流式HTTP/SSE+命令验证旁路的MCP协议)


📌 v3.1.0主要更改

项目 · v2.0.0 v3.0.0 v3.1.0
协议 · REST API · MCP(JSON-RPC 2.0) · MCP(JSON-RPC 2.0)
身份验证 · JWT令牌 · 基于会话(仅限localhost) · 基于会话(仅限localhost)
凭据 · 环境变量(单一) · credentials.json (多个) · credentials.json (多个)
SSH모드 · 仅短暂 · 短暂+持久 · 短暂+持续
Claude Code集成 · curl/脚本MCP本机MCP本机
命令验证 · 需要 · 需要 · 需要(基于规则) · 需要/选择(--dangerously-no-rules)

v3.1.0新增功能:

  • ✨ --dangerously-no-rules 标志:禁用命令验证
  • 🔧 用于开发/测试环境的消除白名单约束选项
  • 📝 运行命令时跟踪详细的日志记录和审核

📌 项目目的

1. 🔒 增强的安全性

解决现有开源MCP项目的安全隐患:

  • SSH密钥文件只存在于本地文件系统中
  • 服务器是 127.0.0.1仅侦听(阻止外部访问)
  • 验证起源头(防止DNS rebinding攻击)
  • 基于白名单/黑名单的命令过滤(Hot-reload)
  • 基于证书文件的管理(.gitignore 处理)

2. 🎓 学习MCP体系结构

通过该项目,您可以学习:

  • 实施模型上下文协议(MCP)服务器
  • 基于HTTP/SSE的JSON-RPC 2.0통신
  • Claude Code本机集成

3. 📚 Node.js+TypeScript实践示例

  • Express.js:构建HTTP服务器
  • TypeScript:类型安全性
  • 节点ssh:SSH客户端
  • 温斯顿:结构化日志记录

🚀 主要功能

MCP工具(Tools)

工具 说明
ssh_execute 在远程服务器上运行SSH命令
ssh_list_credentials 查询注册的凭据列表
ssh_session_info 查询SSH会话状态

安全功能

  • 仅限localhost:仅在127.0.0.1上监听
  • Origin验证:防止DNS rebinding攻击
  • 过滤命令:基于白名单/黑名单的验证(默认)
  • 热重载: rules.json 更改时立即反映
  • 绕过命令验证 (可选): --dangerously-no-rules 可以通过标志从测试环境中移除约束

SSH连接模式

模式 说明
短暂的 (默认) 为每个命令创建/终止新连接
持久 保持连接,cwd跟踪,超时5分钟

📦 技术堆栈

类别 技术 用途
运行时 Node.js 18+ JavaScript执行环境

语言TypeScript类型安全性
Web框架Express.js HTTP/SSE服务器
SSH客户端 · node-ssh · SSH连接和命令执行
日志记录Winston结构化日志记录
安全性 · Helmet · 安全性标头设置


🛠️ 安装和设置

1.安装依赖性```bash

git clone https://github.com/terria1020/local-ssh-mcp.git
cd local-ssh-mcp
npm install


### 2.设置凭据```bash
cp credentials.example.json credentials.json

credentials.json 编辑:```json
{
"version": "1.0",
"credentials": [
{
"id": "my-server",
"name": "My Production Server",
"host": "server.example.com",
"port": 22,
"username": "ubuntu",
"authType": "key",
"privateKeyPath": "/Users/you/.ssh/id_rsa"
},
{
"id": "dev-server",
"name": "Development Server",
"host": "dev.example.com",
"port": 22,
"username": "developer",
"authType": "password",
"password": "base64-encoded-password"
}
]
}


**密码Base64编码:**```bash
echo -n "your-password" | base64

3.设置环境变量(可选)```bash

cp .env.example .env


`.env` 文件:```env
PORT=4000
LOG_LEVEL=info
SESSION_TIMEOUT=300000

4.构建和运行

正常模式(启用命令验证-推荐):```bash

빌드

npm run build

프로덕션 실행

npm start

개발 모드

npm run dev


**NO-RULES模式(禁用命令验证-仅开发/测试环境):**```bash
# 개발 모드
npm run dev -- --dangerously-no-rules

# 프로덕션 모드
npm start -- --dangerously-no-rules

# 또는 직접 실행
node dist/index.js -- --dangerously-no-rules

> ⚠️ 安全警告: --dangerously-no-rules 模式不受限制地运行所有SSH命令。仅在可靠的开发/测试环境中使用。绝对不要在生产环境中使用。

5.确认服务器```bash

curl http://127.0.0.1:4000/mcp/health


______________________________________________________________________

## 🔗 Claude Code集成指南

### 方法1:HTTP/SSE方式(推荐)

#### 步骤1:运行MCP服务器```bash
cd /path/to/local-ssh-mcp
npm run build && npm start

服务器 http://127.0.0.1:4000在中运行。

步骤2:在Claude Code中注册MCP服务器```bash

claude mcp add local-ssh --transport http http://127.0.0.1:4000/mcp


#### 步骤3:验证注册```bash
claude mcp list

输出示例:```
local-ssh: http://127.0.0.1:4000/mcp (connected)
Tools: ssh_execute, ssh_list_credentials, ssh_session_info


#### 检查连接状态

`/mcp` 可以通过命令检查MCP服务器的状态:```
┌─────────────────────────────────────────────────────────────┐
│ Local-ssh MCP Server                                        │
│                                                             │
│ Status: ✔ connected                                         │
│ Auth: ✘ not authenticated  ← 정상 (OAuth 미사용)            │
│ URL: http://127.0.0.1:4000/mcp                              │
│ Tools: 3 tools                                              │
└─────────────────────────────────────────────────────────────┘

> 参考: Auth: ✘ not authenticated正常。此服务器仅用于localhost,因此不使用OAuth身份验证。

方法2:手动设置(.mcp.json)

~/.claude/.mcp.json 或项目根目录的 .mcp.json:```json
{
"mcpServers": {
"local-ssh": {
"type": "http",
"url": "http://127.0.0.1:4000/mcp"
}
}
}


### MCP服务器管理```bash
# 서버 목록
claude mcp list

# 서버 제거
claude mcp remove local-ssh

# 서버 재연결
claude mcp add local-ssh --transport http http://127.0.0.1:4000/mcp

💡 Claude Code使用方案

基本用法

Claude Code以自然语言请求时,自动使用MCP工具:

方案1:检查Pod状态

用户:```
my-server에서 kubectl get pods 실행해줘


**克劳德:**```
파드 상태를 확인하겠습니다.
[ssh_execute 도구 사용: credentialId="my-server", command="kubectl get pods"]

方案2:查看证书列表

用户:```
등록된 SSH 서버 목록을 보여줘


**克劳德:**```
[ssh_list_credentials 도구 사용]

등록된 서버 목록:
1. my-server (server.example.com) - ubuntu
2. dev-server (dev.example.com) - developer

方案3:验证多台服务器

用户:```
my-server와 dev-server의 디스크 사용량을 비교해줘


**克劳德:**```
두 서버의 디스크 사용량을 확인하겠습니다.
[두 서버에 df -h 실행 후 결과 비교 분석]

高级使用

持续会话模式```

my-server에서 persistent 모드로:
1. cd /var/log
2. ls -la
3. tail -n 50 syslog


在持续模式下,工作目录(cwd)将被保留。

#### 日志分析```
dev-server의 nginx 에러 로그에서 최근 500 에러를 찾아 분석해줘

监视资源```

my-server의 메모리 사용량이 높은 프로세스 상위 10개를 보여줘


______________________________________________________________________

## 📡 MCP协议

### 端点

POST/mcpJSON-RPC 2.0请求
GET · /mcp · SSE流
DELETE · /mcp · 会话结束
GET · /mcp/health · Health健康检查

### MCP方法

方法 · 说明
`initialize` · 客户端握手
`initialized` · 初始化完成通知
`ping` · 验证连接
`tools/list` · 可用工具列表
`tools/call` 运行工具

### 手动测试```bash
# MCP 테스트 스크립트
./scripts/test-mcp.sh

# 또는 수동으로
curl -X POST http://127.0.0.1:4000/mcp \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}'

配置文件

credentials.json

保存SSH凭据(gitignore已处理):```json
{
"version": "1.0",
"credentials": [
{
"id": "server-id",
"name": "서버 이름",
"host": "hostname",
"port": 22,
"username": "user",
"authType": "key",
"privateKeyPath": "/path/to/key",
"passphrase": "base64-encoded"
}
]
}


“字段”“必需”“说明”
`id` · 唯一标识符(小写、数字、连字符)
`name` · 宣传名称
`host` · 主机名或IP
`port` · 剧情 · SSH端口(默认:22)
`username` · SSH用户名
`authType` · ✅ · `key` 或者 `password`
`privateKeyPath` · 密钥时的SSH密钥文件路径
`passphrase` · 选择 · 关键路径铣削(base64)
`password` · 密码时 · SSH密码(base64)

### rules.json

命令过滤规则(Hot-reload支持):```json
{
"allowedCommands": [
"kubectl",
"docker",
"ls",
"cat",
"grep"
],
"blockedPatterns": [
"rm -rf",
"shutdown",
"reboot"
]
}

绕过验证选项:

基本上 rules.json使用中定义的规则验证所有命令。要在开发/测试环境中完全禁用验证,请在运行服务器时 --dangerously-no-rules 使用标志:```bash
npm run dev -- --dangerously-no-rules


在此模式下:

- 所有SSH命令运行无限制
- 📝 命令执行 `[NO-RULES MODE]` 记录为前缀
- 在服务器启动时显示明确的警告信息

**使用案例:**

- 测试新命令
- 难以预定义白名单
- CI/CD管道实验

______________________________________________________________________

## 📂 项目结构```
local-ssh-mcp/
├── src/
│   ├── index.ts                    # 서버 엔트리포인트
│   ├── routes/
│   │   ├── mcp-transport.ts        # MCP HTTP 트랜스포트
│   │   ├── mcp-handlers.ts         # MCP 메소드 핸들러
│   │   ├── mcp-tools.ts            # MCP 도구 구현
│   │   └── mcp.ts                  # 헬스/상태 엔드포인트
│   ├── services/
│   │   ├── ssh-manager.ts          # SSH 실행
│   │   ├── session-manager.ts      # 세션 관리
│   │   └── credential-manager.ts   # 자격증명 관리
│   ├── middleware/
│   │   ├── origin-validator.ts     # Origin 검증
│   │   └── validator.ts            # 명령 검증
│   ├── utils/
│   │   ├── logger.ts               # Winston 로거
│   │   ├── json-rpc.ts             # JSON-RPC 유틸리티
│   │   └── base64.ts               # Base64 인코딩
│   └── types/
│       ├── index.ts                # 레거시 타입
│       ├── mcp.ts                  # MCP 타입
│       └── credentials.ts          # 자격증명 타입
├── scripts/
│   └── test-mcp.sh                 # MCP 테스트 스크립트
├── credentials.json                # SSH 자격증명 (gitignore)
├── credentials.example.json        # 자격증명 예시
├── credentials.schema.json         # JSON 스키마
├── rules.json                      # 명령 필터링 규칙
├── .mcp.json.example               # Claude Code 설정 예시
└── CLAUDE.md                       # Claude Code 가이드

🔧 开发命令```bash

npm run build # TypeScript 컴파일
npm start # 프로덕션 실행
npm run dev # 개발 모드 (ts-node)
npm run watch # TypeScript watch 모드
npm run clean # dist/ 삭제


______________________________________________________________________

## 🔒 安全建议

### 1.设置SSH密钥权限```bash
chmod 600 ~/.ssh/id_rsa

2.设置credentials.json权限```bash

chmod 600 credentials.json


### 3.启用命令验证(必需)

在生产环境中始终启用命令验证。 `--dangerously-no-rules` 标记 **千万不要使用**.```bash
# ✅ 프로덕션 (검증 활성화 - 기본값)
npm start

# ❌ 프로덕션 (검증 비활성화 - 금지)
npm start -- --dangerously-no-rules

--dangerously-no-rules 模式为:

  • 不受限制地运行所有SSH命令
  • 无法防止执行恶意命令
  • 系统损坏、数据泄露风险
  • 🚫 禁止使用生产环境

4.NO-RULES模式使用指南

--dangerously-no-rules只在以下环境中使用:

  • 个人开发机器
  • 可靠的内部测试环境
  • 隔离网络(无法外部访问)
  • 生产环境
  • 多用户环境
  • 外部网络暴露环境

5.生产环境```env

NODE_ENV=production
LOG_LEVEL=warn

dangerously-no-rules 플래그 사용 금지


______________________________________________________________________

## 🐛 故障排除

### MCP服务器连接失败

1. 验证服务器是否正在运行:```bash
curl http://127.0.0.1:4000/mcp/health
  1. 重新启动服务器:```bash
    npm run build && npm start

3. 从Claude Code重新连接:```bash
claude mcp remove local-ssh
claude mcp add local-ssh --transport http http://127.0.0.1:4000/mcp

“Credential not found”错误

credentials.json相当于 id验证是否存在:```bash
cat credentials.json | jq '.credentials[].id'


### “命令验证失败”错误

`rules.json`将命令添加到允许列表:```json
{
"allowedCommands": [
"your-command-here"
]
}

保存文件时自动反映(无需重新启动服务器)

SSH连接失败

  1. 手动SSH测试:```bash
    ssh -i ~/.ssh/id_rsa user@host

2. 确认密钥文件路径(`credentials.json`)

1. 启用调试日志:```bash
LOG_LEVEL=debug npm run dev

📝 检查日志```bash

실시간 로그

tail -f logs/combined.log

에러 로그만

tail -f logs/error.log


更改日志级别(`.env`):```env
LOG_LEVEL=debug  # error, warn, info, debug

📧 联系和支持

  • 问题: GitHub问题
  • 讨论: GitHub讨论

常见问题

6 问
答案由本站依据条目字段整理,不引用上游原文
Local Ssh MCP 怎么安装?

资料没有给出安装命令,请到官方仓库或文档按说明接入;这类条目多数是生态应用,或尚未发布可安装包。

Local Ssh MCP 怎么在 Claude 里配置?

它的传输方式未标注,在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,配置才会生效。

Local Ssh MCP 收费吗?

本站不代收费用,也没有标注具体价格。是否收费取决于服务本身和背后的接口额度,正式使用前按官方说明确认。

Local Ssh MCP 需要 API Key 吗?

资料标注需要OAuth 授权认证,使用前准备好对应凭据,并按最小权限配置。

Local Ssh MCP 支持哪些客户端?

资料标注支持 Claude;其他客户端只要能配置 MCP Server,也能用同样的命令或地址接入。

Local Ssh MCP 能提供哪些能力?

资料显示约 3 个工具;能力标签包括 安全协议、JavaScript、Claude、开发工具。具体工具清单以官方文档为准。

热门专题

按标签挑服务器
全部专题 →

服务器信息以作者仓库与官方文档为准;分类、传输方式与鉴权方式的中文说明为中文整理,最近核验 2026-05-17。