Local Ssh MCP

本地SSH MCP服务器

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

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

版本：3.1.0（带流式HTTP/SSE+命令验证旁路的MCP协议）

______________________________________________________________________

📌 v3.1.0主要更改

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）

安全功能

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

SSH连接模式

______________________________________________________________________

📦 技术堆栈

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

______________________________________________________________________

🛠️ 安装和设置

1.安装依赖性

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

2.设置凭据

cp credentials.example.json credentials.json

credentials.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编码：

echo -n "your-password" | base64

3.设置环境变量（可选）

cp .env.example .env

.env 文件：

PORT=4000
LOG_LEVEL=info
SESSION_TIMEOUT=300000

4.构建和运行

正常模式（启用命令验证-推荐）：

# 빌드
npm run build

# 프로덕션 실행
npm start

# 개발 모드
npm run dev

NO-RULES模式（禁用命令验证-仅开发/测试环境）：

# 개발 모드
npm run dev -- --dangerously-no-rules

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

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

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

5.确认服务器

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

______________________________________________________________________

🔗 Claude Code集成指南

方法1：HTTP/SSE方式（推荐）

步骤1:运行MCP服务器

cd /path/to/local-ssh-mcp
npm run build && npm start

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

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

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

步骤3:验证注册

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:

{
  "mcpServers": {
    "local-ssh": {
      "type": "http",
      "url": "http://127.0.0.1:4000/mcp"
    }
  }
}

MCP服务器管理

# 서버 목록
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方法

手动测试

# 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已处理）：

{
  "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支持）：

{
  "allowedCommands": [
    "kubectl",
    "docker",
    "ls",
    "cat",
    "grep"
  ],
  "blockedPatterns": [
    "rm -rf",
    "shutdown",
    "reboot"
  ]
}

绕过验证选项：

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

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 가이드

______________________________________________________________________

🔧 开发命令

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

______________________________________________________________________

🔒 安全建议

1.设置SSH密钥权限

chmod 600 ~/.ssh/id_rsa

2.设置credentials.json权限

chmod 600 credentials.json

3.启用命令验证（必需）

在生产环境中始终启用命令验证。 --dangerously-no-rules 标记 千万不要使用.

# ✅ 프로덕션 (검증 활성화 - 기본값)
npm start

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

--dangerously-no-rules 模式为：

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

4.NO-RULES模式使用指南

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

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

5.生产环境

NODE_ENV=production
LOG_LEVEL=warn
# dangerously-no-rules 플래그 사용 금지

______________________________________________________________________

🐛 故障排除

MCP服务器连接失败

1. 验证服务器是否正在运行：

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

1. 重新启动服务器：

npm run build && npm start

1. 从Claude Code重新连接：

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验证是否存在：

cat credentials.json | jq '.credentials[].id'

“命令验证失败”错误

rules.json将命令添加到允许列表：

{
  "allowedCommands": [
    "your-command-here"
  ]
}

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

SSH连接失败

1. 手动SSH测试：

ssh -i ~/.ssh/id_rsa user@host

1. 确认密钥文件路径（credentials.json)

1. 启用调试日志：

LOG_LEVEL=debug npm run dev

______________________________________________________________________

📝 检查日志

# 실시간 로그
tail -f logs/combined.log

# 에러 로그만
tail -f logs/error.log

更改日志级别（.env):

LOG_LEVEL=debug  # error, warn, info, debug

______________________________________________________________________

📧 联系和支持

• 问题:
• 讨论: