本地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
- 重新启动服务器:```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连接失败
- 手动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讨论
