使用说明

MCP代理内存服务器

轻便、安全 模型上下文协议（MCP） 服务器旨在充当AI代理（如Claude Code）的集中式持久内存。它在VPS上运行，提供读写markdown文件的工具(AGENTS.md)，并自动将数据备份到Google云端硬盘或通过电子邮件。

特性

共享内存： A中心 AGENTS.md 跨会话持久的文件
符合MCP标准： 暴露 read_memory 和 write_memory 与Claude Desktop和Claude Code兼容的工具
安全： 通过HTTPS和自定义保护 X-API-Key 带有Starlette中间件的标头
线程安全： 使用文件锁定(fcntl)防止同时访问时出现竞争情况
仅附录： 防止意外删除历史记录；代理只能添加到日志中
价格限制： 可配置的速率限制，以防止滥用（默认值：60个请求/分钟）
输入验证： 最大规则大小限制（默认值：10KB），自动拒绝超大写入
审核日志记录： 所有安全事件和写入都记录到单独的审核文件中
自动备份： 夜间cron作业会自动将内存文件上传到Google Drive
Gitigned数据： 内存文件充当数据库，不提交到仓库

先决条件

Hetzner VPS 服务 （建议使用Ubuntu 22.04+）或任何Linux服务器
域名指向您的VPS IP（例如。， mcp.yourdomain.com)
谷歌云服务帐户 可以访问共享的Google Drive文件夹（用于备份）

快速启动（地方发展）

1.克隆存储库

git clone https://github.com/youruser/mcp-agent-memory.git
cd mcp-agent-memory

2.运行安装脚本

chmod +x setup.sh
./setup.sh

这将：

创建虚拟环境
安装依赖项
生成随机API密钥
创建 .env 来自模板

3.启动服务器

source venv/bin/activate
uvicorn app:app --reload

服务器将在以下时间启动 http://127.0.0.1:8000.

4.测试服务器

pip install httpx  # For async HTTP client
python test_server.py

项目结构

/opt/mcp-server
├── app.py                # Main MCP server (FastAPI + official MCP SDK)
├── backup.py             # Backup logic (Google Drive with rotation)
├── test_server.py        # Test script for verification
├── setup.sh              # Local setup script
├── AGENTS.md             # The memory file (gitignored)
├── service_account.json  # Google credentials (gitignored)
├── .env                  # Secrets (gitignored)
├── .env.example          # Template for .env
├── .gitignore
└── requirements.txt

配置

所有配置都是通过中的环境变量完成的 .env:

# Security (REQUIRED)
MCP_API_KEY=your_very_secure_random_string_here

# Server Configuration
MEMORY_FILE_PATH=AGENTS.md
AUDIT_LOG_PATH=audit.log
MAX_RULE_SIZE=10000

# Rate Limiting
RATE_LIMIT_REQUESTS=60
RATE_LIMIT_WINDOW=60

# Google Drive Backup
GOOGLE_SERVICE_ACCOUNT_FILE=service_account.json
GOOGLE_DRIVE_FOLDER_ID=your_folder_id_here
BACKUP_RETENTION_DAYS=30

部署指南（Hetzner VPS）

1.系统设置

SSH连接到您的服务器并安装依赖项：

apt update && apt upgrade -y
apt install python3-pip python3-venv nginx git certbot python3-certbot-nginx -y

2.创建非根用户（安全）

useradd -r -s /bin/false mcp-server
mkdir -p /opt/mcp-server
chown mcp-server:mcp-server /opt/mcp-server

3.部署代码

cd /opt/mcp-server
git clone https://github.com/youruser/mcp-agent-memory.git .

# Setup Python environment
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# Create configuration
cp .env.example .env
nano .env  # Fill in your values

# Upload service_account.json via SCP or create with nano

4.系统化服务

创建 /etc/systemd/system/mcp-server.service:

[Unit]
Description=MCP Agent Memory Server
After=network.target

[Service]
User=mcp-server
Group=mcp-server
WorkingDirectory=/opt/mcp-server
Environment="PATH=/opt/mcp-server/venv/bin"
ExecStart=/opt/mcp-server/venv/bin/uvicorn app:app --host 127.0.0.1 --port 8000
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

启用并启动：

systemctl daemon-reload
systemctl enable --now mcp-server
systemctl status mcp-server  # Verify it's running

5.Nginx反向代理（HTTPS）

创建 /etc/nginx/sites-available/mcp:

server {
    server_name mcp.yourdomain.com;

    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

        # SSE Support (Critical for MCP)
        proxy_buffering off;
        proxy_cache off;
        proxy_set_header Connection '';
        proxy_http_version 1.1;
        chunked_transfer_encoding off;
    }
}

使用Certbot激活和保护：

ln -s /etc/nginx/sites-available/mcp /etc/nginx/sites-enabled/
nginx -t
systemctl restart nginx
certbot --nginx -d mcp.yourdomain.com

备份配置

系统使用 backup.py 上传 AGENTS.md 自动轮换到谷歌云端硬盘。

谷歌云设置

在Google Cloud控制台中创建项目
启用 Google Drive API
创建一个 服务账号 并下载JSON密钥
分享您的目标Google Drive文件夹中包含服务帐户的电子邮件（授予其“编辑”权限）
拿到 文件夹ID 从文件夹的URL

定时任务

跑 crontab -e 并添加：

# Run backup every night at 3:00 AM
0 3 * * * cd /opt/mcp-server && ./venv/bin/python backup.py >> /var/log/mcp_backup.log 2>&1

手动备份命令

cd /opt/mcp-server
source venv/bin/activate

# Create backup now
python backup.py backup

# List all backups
python backup.py list

# View backup stats
python backup.py stats

# Cleanup old backups manually
python backup.py cleanup

连接代理

克劳德代码（CLI）

claude --mcp-server-url "https://mcp.yourdomain.com/mcp/sse" \
       --mcp-server-header "X-API-Key: your_secure_key"

Claude桌面应用程序

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json （macOS）：

{
  "mcpServers": {
    "remote-memory": {
      "command": "",
      "url": "https://mcp.yourdomain.com/mcp/sse",
      "headers": {
        "X-API-Key": "your_secure_key"
      }
    }
  }
}

API 参考

MCP工具

`read_memory`

说明： 读取包含共享代理知识的AGENTS.md内存文件
退货： 内存文件的完整标记内容

`write_memory`

说明： 将新规则、学习或注释附加到记忆文件中
论据：
- rule （string）：要附加的文本（最大10KB，自动加时间戳）
退货： 成功消息或错误描述

REST API端点

不支持MCP的客户端的替代端点：

端点	方法	身份验证	描述
`/`	GET	否	服务信息
`/health`	GET	否	公共卫生检查
`/health/secure`	GET	是	使用配置进行身份验证的健康检查
`/api/memory`	GET	是	读取内存文件
`/api/memory?rule=...`	POST	是	写入内存文件
`/docs`	GET	否	OpenAPI文档

安全说明

API密钥： 这 X-API-Key 所有MCP和受保护的REST请求都需要标头
速率限制： 默认每个IP地址每分钟60个请求
输入验证： 超过10KB的规则被拒绝
审核日志记录： 记录到的所有安全事件 audit.log
数据持久性： AGENTS.md 被忽略，仅存在于磁盘上
非根服务： Systemd以专用方式运行 mcp-server 用户
并发： 写入操作使用独占文件锁(fcntl.LOCK_EX)

监控

查看日志

# Application logs
journalctl -u mcp-server -f

# Audit log (security events)
tail -f /opt/mcp-server/audit.log

# Backup log
tail -f /var/log/mcp_backup.log

健康检查

# Public health check
curl https://mcp.yourdomain.com/health

# Authenticated health check
curl -H "X-API-Key: your_key" https://mcp.yourdomain.com/health/secure

故障排除

服务器无法启动

检查日志： journalctl -u mcp-server -e
验证 .env 存在并具有 MCP_API_KEY 集
确保端口8000可用

MCP连接失败

验证SSE端点： curl -H "X-API-Key: your_key" https://mcp.yourdomain.com/mcp/sse
检查nginx是否正确代理： nginx -t
确保SSL证书有效

备份失败

验证 service_account.json 存在且有效
检查服务帐户是否有权访问Google Drive文件夹
查看备份日志： cat /var/log/mcp_backup.log

许可证

麻省理工学院

来源

此实现使用：

MCP官方Python SDK -协议实施
FastMCP文档 -FastAPI集成模式
快速API -Web框架