解决MCP Server SSH远程路径配置问题：macOS与Linux路径差异

在开发基于Model Context Protocol (MCP)的博客管理工具时，遇到了一个典型的跨平台路径配置问题。本文详细记录了问题的发现、分析和解决过程，希望能帮助遇到类似问题的开发者。

问题现象

MCP Server astro-blog-ssh 在启动时报错：

failed to initialize MCP client for astro-blog-ssh: MCP 服务启动失败: Error: Command failed: ssh -p 7122 -o BatchMode=yes -o StrictHostKeyChecking=accept-new -i /Users/mhl/.ssh/id_ed25519 mahongliang@111.228.52.26 mkdir -p '/home/mahongliang/workspace/astro-site/content/blog' && test -d '/home/mahongl...

问题分析

1. 初步排查

首先确认SSH密钥文件权限正确（600），SSH连接本身能够正常建立：

ssh -p 7122 -o BatchMode=yes -o StrictHostKeyChecking=accept-new -i /Users/mhl/.ssh/id_ed25519 mahongliang@111.228.52.26 "echo 'SSH connection successful'"

2. 深入诊断

执行完整的目录创建命令时发现问题：

ssh -p 7122 -o BatchMode=yes -o StrictHostKeyChecking=accept-new -i /Users/mhl/.ssh/id_ed25519 mahongliang@111.228.52.26 "mkdir -p '/home/mahongliang/workspace/astro-site/content/blog' && test -d '/home/mahongliang/workspace/astro-site/content/blog'"

返回错误：mkdir: /home/mahongliang: Operation not supported

3. 根本原因

通过查询远程服务器的用户主目录：

ssh -p 7122 -o BatchMode=yes -o StrictHostKeyChecking=accept-new -i /Users/mhl/.ssh/id_ed25519 mahongliang@111.228.52.26 "echo \$HOME"

发现返回结果是：/Users/mahongliang

这说明远程服务器实际上是macOS系统，而不是假设的Linux系统！

• Linux系统：用户主目录为 `/home/ `
• macOS系统：用户主目录为 `/Users/ `

解决方案

将MCP配置中的远程路径从Linux路径改为macOS路径：

错误配置：

"BLOG_REMOTE_POSTS_DIR": "/home/mahongliang/workspace/astro-site/content/blog"

正确配置：

"BLOG_REMOTE_POSTS_DIR": "/Users/mahongliang/workspace/astro-site/content/blog"

验证修复

使用修正后的路径测试：

ssh -p 7122 -o BatchMode=yes -o StrictHostKeyChecking=accept-new -i /Users/mhl/.ssh/id_ed25519 mahongliang@111.228.52.26 "mkdir -p '/Users/mahongliang/workspace/astro-site/content/blog' && test -d '/Users/mahongliang/workspace/astro-site/content/blog' && echo 'Directory check successful'"

返回：Directory check successful

MCP Server成功启动：

Astro Blog SSH MCP Server 已启动 -> mahongliang@111.228.52.26:/Users/mahongliang/workspace/astro-site/content/blog

经验总结

1. 不要假设远程系统类型：在配置远程路径时，务必确认远程操作系统的实际类型
2. 动态验证路径：使用 echo $HOME 命令获取远程用户的实际主目录路径
3. 跨平台兼容性：在开发工具时考虑不同操作系统的路径差异
4. 详细的错误日志：保留完整的错误信息有助于快速定位问题

这个问题虽然简单，但体现了开发中常见的”假设陷阱”。通过系统性的排查和验证，我们能够快速找到并解决问题。

相关技术栈

• MCP (Model Context Protocol): 标准化的AI上下文协议
• Astro: 现代化静态站点生成器
• SSH: 安全远程连接协议
• macOS/Linux: 不同的操作系统路径约定