使用说明

vpc同步mcp服务器

一个MCP（模型上下文协议）服务器，用于保持您之间的上下文同步 本地克劳德桌面/Claude.ai 和 远程VPC实例 在TMUX会话中运行Claude Code。

起草提示并在本地进行分析，将其推送到VPC执行，并将结果拉回来——所有这些都是通过Claude的原生工具界面完成的。

建筑

┌─────────────────────┐         ┌──────────────────────────────┐
│  LOCAL MACHINE       │         │  VPC (cloud server)          │
│                      │         │                              │
│  Claude Desktop      │◄──SSH──►│  vpc-sync-mcp-server         │
│  (MCP client)        │  tunnel │  (Streamable HTTP on :3847)  │
│                      │         │       │                      │
│  • Draft prompts     │         │       ├── TMUX session A     │
│  • Review results    │         │       │   └── Claude Code    │
│  • Analyze projects  │         │       ├── TMUX session B     │
│                      │         │       │   └── Claude Code    │
│                      │         │       └── Context Store      │
│                      │         │           (SQLite)            │
└─────────────────────┘         └──────────────────────────────┘

工具（14）

类别	工具	描述
提示	`vpc_push_prompt`	向VPC上下文存储推送提示
	`vpc_pull_results`	撤回执行结果和日志
	`vpc_list_prompts`	列出/筛选已存储的提示
子速率复用器	`vpc_list_sessions`	列出活动的TMUX会话
	`vpc_session_capture`	捕获窗格回滚内容
	`vpc_send_to_session`	将文本/命令发送到TMUX窗格
上下文	`vpc_sync_context`	推/拉结构化项目上下文
	`vpc_list_projects`	列出已注册的项目
文件	`vpc_read_file`	从VPC文件系统读取文件
	`vpc_write_file`	将文件写入VPC文件系统
	`vpc_list_dir`	列出目录内容
工作流程	`vpc_dispatch_workflow`	多步骤：存储提示+写入文件+发送到TMUX
	`vpc_get_status`	整体VPC状态：会话、提示、磁盘、正常运行时间

先决条件

垂直路径计算机：具有Node.js 20+、tmux和SSH访问权限的Linux服务器（Ubuntu推荐）
本地：克劳德桌面（macOS或Windows），npm/npx
可选的: inotify-tools 用于新项目的自动注册
可选的：VPC上安装了Claude Code(npm install -g @anthropic-ai/claude-code)

快速开始

1.在VPC上安装tmux（如果尚未安装）

# Ubuntu/Debian
sudo apt-get update && sudo apt-get install -y tmux

# CentOS/RHEL
sudo yum install -y tmux

# Verify
tmux -V

2.部署MCP服务器

git clone https://github.com/gregdigittal/vpc-sync-mcp-server.git
cd vpc-sync-mcp-server
npm install
npm run build

# Generate an API key
export VPC_SYNC_API_KEY=$(openssl rand -hex 32)
echo "Save this key: $VPC_SYNC_API_KEY"

# Run in a persistent tmux session
tmux new-session -d -s mcp-server \
  "VPC_SYNC_API_KEY=$VPC_SYNC_API_KEY \
   VPC_SYNC_BASE_DIR=$HOME \
   VPC_SYNC_DB_PATH=$HOME/vpc-sync.db \
   node dist/index.js"

# Verify
curl http://127.0.0.1:3847/health

3.为Claude Code设置TMUX会话

MCP服务器管理在TMUX会话中运行的Claude Code实例。即使您断开与SSH的连接，TMUX也会使会话保持活动状态，因此您的Claude Code实例可以全天候运行。

为项目创建Claude Code会话

# Create a named session for a project
tmux new-session -d -s my-project -c ~/projects/my-project

# Launch Claude Code inside it
tmux send-keys -t my-project 'claude' Enter

一次创建多个项目会话

for project in webapp api-service data-pipeline; do
  tmux new-session -d -s "$project" -c ~/projects/"$project"
  tmux send-keys -t "$project" 'claude' Enter
  echo "Created session: $project"
done

基本tmux命令

# List all sessions
tmux list-sessions

# Attach to a session (to see what Claude Code is doing)
tmux attach -t my-project

# Detach without killing the session: press Ctrl+B then D

# Kill a session when done
tmux kill-session -t my-project

关键概念：当您从tmux会话中分离或SSH连接断开时，会话将继续在后台运行。克劳德代码继续工作。您可以随时重新连接，或使用 vpc_session_capture 在没有SSH登录的情况下，从笔记本电脑查看发生了什么。

增加tmux回滚缓冲区

默认情况下，tmux保留2000行历史记录。对于Claude Code输出，您需要更多。添加 ~/.tmux.conf:

cat >> ~/.tmux.conf << 'EOF'
set-option -g history-limit 50000
EOF

# Reload (applies to new sessions)
tmux source-file ~/.tmux.conf

使会话在重新启动后仍然有效

在以下位置创建启动脚本 ~/start-sessions.sh:

#!/bin/bash
# start-sessions.sh — Recreate tmux sessions after reboot

API_KEY="YOUR_KEY_HERE"

# Start the MCP server
tmux new-session -d -s mcp-server \
  "VPC_SYNC_API_KEY=$API_KEY \
   VPC_SYNC_BASE_DIR=$HOME \
   VPC_SYNC_DB_PATH=$HOME/vpc-sync.db \
   node $HOME/vpc-sync-mcp-server/dist/index.js"

# Start the project watcher (requires inotify-tools)
tmux new-session -d -s project-watcher \
  "VPC_SYNC_API_KEY=$API_KEY $HOME/vpc-sync-mcp-server/scripts/auto-register-projects.sh"

# Start Claude Code sessions for active projects
for project in webapp api-service; do
  if [ -d "$HOME/projects/$project" ]; then
    tmux new-session -d -s "$project" -c "$HOME/projects/$project"
    # Uncomment to auto-launch Claude Code:
    # tmux send-keys -t "$project" 'claude' Enter
  fi
done

echo "All sessions started. Run 'tmux list-sessions' to verify."

chmod +x ~/start-sessions.sh

添加到crontab以在启动时运行：

crontab -e
# Add this line:
@reboot sleep 10 && /home/youruser/start-sessions.sh

或者使用systemd进行更可靠的启动：

sudo tee /etc/systemd/system/vpc-sync-sessions.service << EOF
[Unit]
Description=VPC Sync TMUX Sessions
After=network.target

[Service]
Type=forking
User=youruser
ExecStart=/home/youruser/start-sessions.sh
RemainAfterExit=yes

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl enable vpc-sync-sessions
sudo systemctl start vpc-sync-sessions

4.从本地计算机连接

在Mac/PC上打开终端选项卡并创建SSH隧道（保持其运行）：

ssh -L 3847:127.0.0.1:3847 user@your-vpc-ip -N

这 -N 标志表示“没有远程命令”——终端将显示卡住。这很正常。只要此选项卡保持打开状态，隧道就会处于活动状态。

要使隧道持久并自动重新连接，请执行以下操作：

# macOS
brew install autossh
autossh -M 0 -f -N -L 3847:127.0.0.1:3847 user@your-vpc-ip

# Linux
sudo apt-get install -y autossh
autossh -M 0 -f -N -L 3847:127.0.0.1:3847 user@your-vpc-ip

5.配置克劳德桌面

添加到您的Claude Desktop配置文件中：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
视窗: %APPDATA%\Claude\claude_desktop_config.json

如果您已经有一个包含首选项的配置文件，请添加 mcpServers 在现有设置旁边进行阻止：

{
  "mcpServers": {
    "vpc-sync": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://localhost:3847/mcp",
        "--header",
        "Authorization: Bearer YOUR_API_KEY",
        "--allow-http"
      ]
    }
  }
}

重新启动克劳德桌面。14 vpc_* 工具将会出现。

重要提示： 这 --allow-http 标志是强制性的。没有它， mcp-remote 尝试OAuth动态客户端注册(POST /register)，这会导致404循环和静默工具调用挂起——工具显示为已注册，但所有调用都超时，没有服务器端日志。

6.注册您的项目

# On the VPC — register all existing projects
VPC_SYNC_API_KEY=your-key ./scripts/register-all-projects.sh

# Auto-register new projects going forward (run in tmux)
sudo apt-get install -y inotify-tools  # if not installed
tmux new-session -d -s project-watcher \
  "VPC_SYNC_API_KEY=your-key ./scripts/auto-register-projects.sh"

注：对MCP服务器的所有curl请求都需要三个标头： Content-Type: application/json, Accept: application/json, text/event-stream，以及 Authorization: Bearer KEY.失踪 Accept 返回a Not Acceptable 错误。

配置

环境变量	默认值	描述
`VPC_SYNC_API_KEY`	（必填）	用于身份验证的承载令牌
`VPC_SYNC_BASE_DIR`	`$HOME`	文件操作的根目录
`VPC_SYNC_DB_PATH`	`./vpc-sync.db`	SQLite数据库路径
`VPC_SYNC_PROJECTS_DIR`	`$HOME/projects`	自动注册关注目录
`PORT`	`3847`	HTTP服务器端口
`BIND`	`127.0.0.1`	绑定地址（仅保留SSH的本地主机）
`TRANSPORT`	`http`	运输： `http` 或 `stdio`

工作流

从笔记本电脑开始一个新项目

集思广益第.ai条中的要求
vpc_sync_context （推）→ 在VPC上存储项目上下文
vpc_push_prompt → 发送执行提示
vpc_dispatch_workflow → 写入文件+发送到Claude Code会话
vpc_pull_results → 查看已构建的内容
vpc_session_capture → 检查实时输出

审查现有项目

vpc_list_projects → 查看VPC上的内容
vpc_sync_context （拉）→ 将上下文加载到本地Claude中
vpc_read_file → 提取密钥文件
在本地起草反馈
vpc_push_prompt → 发送评论提示
vpc_dispatch_workflow → 让克劳德密码来处理

监控多个会话

vpc_get_status → 一切概述
vpc_session_capture → 检查每个会话
vpc_pull_results → 抓取已完成的工作

安全

认证：持票人代币通过 Authorization 头球
绑定：仅限本地主机(127.0.0.1)--通过SSH隧道访问
路径净化：所有文件操作仅限于 VPC_SYNC_BASE_DIR
TMUX净化：从中删除控制字符 vpc_send_to_session
速率限制：每个客户端每分钟100个请求
没有OAuth：使用简单的共享密钥——服务器永远不会暴露在互联网上

故障排除

Claude Desktop显示工具但调用超时

检查 mcp-remote 登录您的Mac：

tail -50 ~/Library/Logs/Claude/mcp-server-vpc-sync.log

常见原因：SSH隧道掉线（重启），服务器崩溃（检查 tmux attach -t mcp-server)，或服务器和客户端配置之间的API密钥不匹配。

SSH隧道似乎卡住了

这很正常 -N 标志表示“没有远程命令”。隧道正在工作。测试：

curl http://localhost:3847/health

`Cannot POST /register` 日志中的错误

这意味着 mcp-remote 正在尝试OAuth发现。确保 --allow-http 位于您的Claude Desktop配置参数中。

服务器无法启动--端口正在使用中

lsof -i :3847    # Find what's using the port
PORT=3848 node dist/index.js   # Use a different port

TMUX会话终止或Claude Code退出

# Check if session still exists
tmux list-sessions

# If gone, recreate it
tmux new-session -d -s my-project -c ~/projects/my-project
tmux send-keys -t my-project 'claude' Enter

发展

npm install
npm run dev      # Run with tsx (auto-reload)
npm run build    # Compile TypeScript
npm start        # Run compiled JS

许可证

麻省理工学院——见许可证