Hermes MCP

爱马仕MCP

Claude Desktop的轻量级、可靠的MCP服务器，配备15个基本开发工具。

平台： Windows（使用PowerShell，Git作为Windows路径）\ 主要特点： 修复了导致工具挂起的关键异步子进程stdin继承错误。

为什么选择爱马仕？

大多数MCP文件/shell服务器都很脆弱。爱马仕是：

• 可靠的 -使用stdin隔离进行正确的异步子进程处理
• 完成 -15个工具，涵盖文件、shell、git、HTTP和系统实用程序
• 简单 -纯Python，约700行，易于理解和修改
• 快速 -直接执行，无不必要的开销

平台支持

当前Windows已优化：

• 用途 powershell.exe 对于shell命令
• Git路径默认为 C:\Program Files\Git\
• 路径分隔符为Windows样式

需要Unix/Mac适配：

• 替换 run_powershell 随着 run_bash
• 更新git可执行文件检测
• 调整路径处理

欢迎支持Unix/Mac的PR！

关键修复

如果你正在构建生成子流程的MCP工具，你会遇到这个问题： 子进程继承MCP的stdin管道并挂起等待输入.

修复方法：

process = await asyncio.create_subprocess_exec(
    executable, *args,
    stdin=asyncio.subprocess.DEVNULL,  # THIS IS THE KEY
    stdout=asyncio.subprocess.PIPE,
    stderr=asyncio.subprocess.PIPE,
)

没有 stdin=asyncio.subprocess.DEVNULLgit和shell命令将在Claude Desktop中无限期挂起。

工具（15）

文件操作（10）

Shell和Git（2）

Web和API（2）

系统（1）

安装

先决条件

• Windows 10/11
• Python 3.10+
• Git for Windows
• 克劳德桌面

1.克隆仓库

git clone https://github.com/YOUR_USERNAME/hermes-mcp.git
cd hermes-mcp

2.创建虚拟环境

python -m venv .venv
.venv\Scripts\activate

3.安装依赖项

pip install -r requirements.txt

4.配置允许的路径

编辑 server.py 并更新 ALLOWED_PATHS 列表以匹配您的系统：

ALLOWED_PATHS = [
    Path("C:/Users/YOUR_USERNAME/Documents"),
    Path("C:/Users/YOUR_USERNAME/Projects"),
    # Add your paths here
]

5.添加到Claude桌面配置

编辑 %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "hermes": {
      "command": "C:\\path\\to\\hermes-mcp\\.venv\\Scripts\\python.exe",
      "args": ["C:\\path\\to\\hermes-mcp\\server.py"]
    }
  }
}

6.重新启动克劳德桌面

使用示例

# Read a file
hermes:read_file path="C:\Users\me\project\README.md"

# Git operations
hermes:run_git args="status" working_directory="C:\Users\me\project"
hermes:run_git args="log --oneline -5" working_directory="C:\Users\me\project"

# Search for files
hermes:search_files path="C:\Users\me\project" pattern="*.py"

# Fetch a webpage
hermes:fetch_url url="https://example.com"

# API call
hermes:http_request method="GET" url="https://api.github.com/zen"

# POST with JSON
hermes:http_request method="POST" url="https://api.example.com/data" json_body={"key": "value"}

# Get current time
hermes:get_time

安全

• 文件操作仅限于中的路径 ALLOWED_PATHS
• Web/API工具没有URL限制（有意用于开发）
• 无身份验证或速率限制（仅限本地使用）

依赖项

• mcp -模型上下文协议SDK
• httpx -异步HTTP客户端

技术细节

异步子进程模式

async def run_command(...):
    process = await asyncio.create_subprocess_exec(
        executable, *args,
        stdin=asyncio.subprocess.DEVNULL,  # Prevents stdin inheritance
        stdout=asyncio.subprocess.PIPE,
        stderr=asyncio.subprocess.PIPE,
        cwd=working_dir
    )
    
    try:
        stdout, stderr = await asyncio.wait_for(
            process.communicate(),
            timeout=30
        )
    except asyncio.TimeoutError:
        process.kill()
        await process.wait()
        # Handle timeout

为什么stdin=DEVNULL？

MCP服务器通过stdio进行通信。生成子进程时，默认情况下它会继承父进程的stdin。这意味着：

1. 子进程的stdin指向MCP的通信管道
2. 如果子进程试图读取stdin（git、shell等），它会阻止
3. 它读取的MCP消息不是有效输入，导致挂起或错误

设置 stdin=DEVNULL 告诉子流程“您没有stdin”——它不会试图读取，也不会干扰MCP的通信。

故障排除

工具无限期悬挂

• 检查一下 stdin=asyncio.subprocess.DEVNULL 已设置
• 验证可执行路径是否存在

“不允许路径”错误

• 将您的路径添加到 ALLOWED_PATHS 在server.py中

找不到Git

• 安装Windows版Git
• 检查中的路径 run_git 匹配您的安装

贡献

PR欢迎。关键领域：

• Unix/Mac支持 -用bash替换PowerShell，更新路径
• 附加工具
• 更好的错误消息

许可证

麻省理工学院

鸣谢

stdin修复是通过痛苦的调试发现的，希望它能节省您的时间。

______________________________________________________________________

*以神的使者赫尔墨斯命名，因为MCP服务器就是这么做的。*