jaimealberto/harper-mcps
GitHub: jaimealberto/harper-mcps
为Claude Code提供MCP协议服务器，用于管理Obsidian vault、执行SSH命令、控制Windows系统并进行OSINT研究。
Stars: 0 | Forks: 0
# harper-mcps
用于 [Claude Code](https://claude.ai/code) 的 MCP (_Model Context Protocol_) 服务器集合，可管理基础设施、访问 Obsidian vault、管理 Windows 机器并执行 OSINT 调研。
专为自管理的 homelab 设计。所有服务器均使用 stdio 传输方式，不依赖 FastMCP，实现快速启动（<20ms）。
## 包含的服务器
| 服务器 | 工具 | 依赖项 |
|--------|------|--------|
| `mcp_obsidian_server.py` | search, read, write, list, tags, backlinks, structure | `mcp` |
| `mcp_ssh_server.py` | ssh_run, ssh_read/write_file, ssh_check, nmap_discover/scan/audit | `nmap` (系统) |
| `mcp_winrm_server.py` | winrm_run_ps, winrm_read/write_file, winrm_install, winrm_check | `pywinrm` |
| `mcp_osint_server.py` | username, email, social, domain, whois, dns, phone, ip, breach, dossier | 见下文 |
## 快速安装
### 1. 克隆仓库
```
git clone https://github.com/JaimeAlberto/harper-mcps.git
cd harper-mcps
```
### 2. 安装依赖
**MCP Obsidian：**
```
pip install mcp
```
**MCP SSH + nmap：**
```
# 无 Python 依赖——使用系统自带的 ssh 和 nmap
sudo apt install nmap # Debian/Ubuntu
# brew install nmap # macOS
```
**MCP WinRM：**
```
pip install pywinrm urllib3
```
**MCP OSINT：**
```
# 基础库（必需）：
pip install python-whois dnspython phonenumbers
# 可选工具（用于深入搜索）：
pip install maigret holehe sherlock-project theHarvester
```
### 3. 配置
复制示例配置文件：
```
cp .env.example .env
# 编辑 .env 文件填写路径
cp winrm_hosts.example.json ~/.claude/winrm_hosts.json
chmod 600 ~/.claude/winrm_hosts.json
# 编辑并填写你的 Windows 主机和凭据
```
### 4. 添加到 Claude Code
在 `~/.claude.json` 文件的 `mcpServers` 键下添加（或使用 `claude mcp add` 命令）：
```
{
"mcpServers": {
"harper-obsidian": {
"type": "stdio",
"command": "python3",
"args": ["/ruta/a/harper-mcps/mcp_obsidian_server.py"],
"env": {
"OBSIDIAN_VAULT": "/home/tuusuario/Obsidian"
}
}
}
}
```
查阅 `claude_settings_example.json` 可以查看同时配置四个服务器的示例。
## 各服务器详情
### MCP Obsidian (`harper-obsidian`)
允许 Claude Code 直接读写你的 [Obsidian](https://obsidian.md) vault。
📄 [完整文档 → docs/obsidian.md](docs/obsidian.md)
**环境变量：**
| 变量 | 默认值 | 描述 |
|------|--------|------|
| `OBSIDIAN_VAULT` | `~/Obsidian` | vault 路径 |
**可用工具：**
| 工具 | 描述 |
|------|------|
| `search_vault` | 在所有笔记中搜索文本，并显示上下文片段 |
| `read_note` | 根据相对于 vault 的路径读取笔记 |
| `write_note` | 写入或覆盖笔记 |
| `list_notes` | 列出目录下的笔记（递归） |
| `find_by_tag` | 通过前置信息或正文中的标签查找笔记 |
| `get_backlinks` | 查找链接到特定笔记的其他笔记 |
| `vault_structure` | 显示文件夹结构及笔记数量 |
**使用示例：**
- “在我的 vault 中搜索关于 Python 的笔记”
- “读取笔记 Proyectos/mi-proyecto.md”
- “列出所有带有 #pendiente 标签的笔记”
- “哪些笔记链接到了 weekly-review 笔记？”
### MCP SSH + nmap (`harper-ssh`)
通过 SSH 在远程 Linux/Unix 主机上执行命令，并使用 nmap 扫描网络。
从 `~/.ssh/config` 读取主机配置 — 不存储密码。
📄 [完整文档 → docs/ssh.md](docs/ssh.md)
**亮点特性：**
- 写入文件前自动备份（创建 `fichero.harper.YYYY-MM-DD`）
- 检测命令中的写入操作，并对目标文件进行备份
- 使用 nmap 进行 ping 扫描、端口扫描和完整服务审计
**可用工具：**
| 工具 | 描述 |
|------|------|
| `ssh_list_hosts` | 列出 `~/.ssh/config` 中的主机，包括 IP 和用户 |
| `ssh_run` | 在远程主机上执行命令 |
| `ssh_read_file` | 读取远程文件内容 |
| `ssh_write_file` | 写入远程文件（带自动备份） |
| `ssh_check` | 检查与主机的 SSH 连通性 |
| `ssh_check_all` | 同时检查所有主机 |
| `nmap_discover` | Ping 扫描：发现网络中的活跃主机 |
| `nmap_scan` | 对一个或多个主机进行端口扫描 |
| `nmap_audit` | 完整审计：服务版本 + NSE 脚本 |
**使用示例：**
- “列出我的 SSH 主机”
- “在 servidor01 上执行 `df -h`”
- “扫描 192.168.1.0/24 网段的 22,80,443 端口”
- “我的网络中哪些主机是活跃的？”
### MCP WinRM (`harper-winrm`)
通过 WinRM（Windows 远程管理）远程管理 Windows 机器。
📄 [完整文档 → docs/winrm.md](docs/winrm.md)
**Windows 端要求**（需以管理员身份执行）：
```
Enable-PSRemoting -Force
# HTTPS（推荐）：
New-SelfSignedCertificate -DnsName "NOMBRE_PC" -CertStoreLocation Cert:\LocalMachine\My
winrm create winrm/config/Listener?Address=*+Transport=HTTPS @{Port="5986";CertificateThumbprint="THUMBPRINT"}
```
**凭证文件** (`~/.claude/winrm_hosts.json`, 权限 chmod 600)：
```
{
"hosts": {
"mi-pc": {
"endpoint": "https://192.168.1.100:5986/wsman",
"username": "administrador",
"password": "tu-contraseña",
"transport": "basic",
"server_cert_validation": "ignore",
"message_encryption": "never"
}
}
}
```
**环境变量：**
| 变量 | 默认值 | 描述 |
|------|--------|------|
| `WINRM_HOSTS_CONFIG` | `~/.claude/winrm_hosts.json` | 凭证文件路径 |
**可用工具：**
| 工具 | 描述 |
|------|------|
| `winrm_list_hosts` | 列出已配置的主机及其凭证状态 |
| `winrm_run_ps` | 在 Windows 主机上执行 PowerShell 脚本 |
| `winrm_read_file` | 读取 Windows 文件内容 |
| `winrm_write_file` | 写入 Windows 文件（带自动备份） |
| `winrm_install` | 通过 winget 安装软件 |
| `winrm_check` | 检查 WinRM 连通性 |
**使用示例：**
- “我的电脑 my-pc 开机了吗？”
- “在 my-pc 上执行 `winget upgrade` 并显示待更新项”
- “通过 winget 在 my-pc 上安装 Mozilla.Firefox”
- “读取 my-pc 上的 C:\Users\usuario\AppData\Local\app\config.ini 文件”
### MCP OSINT (`harper-osint`)
集成到 Claude Code 中的开源情报工具。封装了 maigret、holehe、sherlock、theHarvester 和标准库。
📄 [完整文档 → docs/osint.md](docs/osint.md)
**环境变量：**
| 变量 | 默认值 | 描述 |
|------|--------|------|
| `OSINT_VAULT` | `~/osint-reports` | 保存报告的目录 |
| `THEHARVESTER_BIN` | 自动检测 | theHarvester 二进制文件路径 |
**可用工具：**
| 工具 | 功能 | 依赖 |
|------|------|------|
| `osint_status` | 检查已安装的工具 | — |
| `osint_username` | 在 3000+ 网站搜索用户名 (Maigret) | `pip install maigret` |
| `osint_email` | 在 120+ 服务搜索邮箱 (Holehe) | `pip install holehe` |
| `osint_social_scan` | 在 400+ 社交网络搜索用户名 (Sherlock) | `pip install sherlock-project` |
| `osint_domain` | 搜索邮箱/子域名/IP (TheHarvester) | `pip install theHarvester` |
| `osint_whois` | 查询域名或 IP 的 WHOIS 信息 | `pip install python-whois` |
| `osint_dns` | 完整 DNS 查询 + SPF/DMARC/DKIM | `pip install dnspython` |
| `osint_phone` | 查询电话号码的国家/运营商/类型 | `pip install phonenumbers` |
| `osint_ip` | 查询公网 IP 的 ASN/地理位置/滥用信息 | — (使用 ipinfo.io) |
| `osint_breach_check` | 检查邮箱是否出现在数据泄露中 (HIBP) | — (可选 API 密钥) |
| `osint_dossier` | 综合所有工具生成完整报告 | 根据目标类型 |
**使用示例：**
- “检查已安装的 OSINT 工具状态”
- “对 example.com 执行 WHOIS 查询”
- “分析 empresa.com 的 DNS 记录，告诉我它是否有 SPF 和 DMARC”
- “邮箱 usuario@ejemplo.com 是否出现在数据泄露中？”
- “生成关于域名 empresa.com 的完整报告”
## 安全注意事项
- **MCP SSH：** 不存储凭证 — 使用 `~/.ssh/config` 和 SSH 密钥。
- **MCP WinRM：** 凭证存储在仓库外的 `winrm_hosts.json` 文件中。保持 `chmod 600` 权限，切勿提交到版本库。
- **MCP OSINT：** 所有工具都会进行网络请求。请遵守各平台的使用限制和服务条款。
- **nmap：** 某些扫描类型需要 root 权限。服务器使用 `-sT` (TCP connect) 方式，不需要特殊权限。
## 许可证
MIT 许可证。使用风险自负。这些工具会进行真实的网络连接并可能修改远程系统。
标签：逆向工具