🚂 Letta MCP Server Railway 版本

云优化的HTTP传输版Letta MCP服务器 - 在30秒内部署到Railway。

通用的MCP服务器，通过流式HTTP连接任何AI客户端到Letta.ai的强大有状态代理，实现无缝云部署。

---

🚀 快速部署到 Railway

预备条件

• Letta API密钥 从 api.letta.com 获取（提供免费层级）
• Railway账户 （免费层级包括每月500小时）

一键部署

1. 点击上方的部署按钮
2. 连接您的GitHub账户 到Railway
3. 添加环境变量：LETTA_API_KEY=your_letta_api_key_here
4. 部署 - 您的MCP服务器将在不到2分钟内上线！

您的MCP服务器URL

https://your-app-name.up.railway.app/mcp

---

⚡ 与AI客户端集成

Claude Desktop (ADE集成)

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

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "letta-railway": {
      "url": "https://your-app.up.railway.app/mcp",
      "transport": "streamable_http",
      "timeout": 300,
      "headers": {
        "User-Agent": "Claude-Desktop-MCP/1.0"
      }
    }
  }
}

MCP Inspector测试

使用MCP Inspector测试您的部署：

npx @modelcontextprotocol/inspector https://your-app.up.railway.app/mcp

GitHub Copilot & VS Code

{
  "mcp.servers": {
    "letta-railway": {
      "transport": "streamable_http",
      "url": "https://your-app.up.railway.app/mcp"
    }
  }
}

其他MCP客户端

• Cursor: 添加服务器到MCP配置
• Replit: 使用兼容MCP的端点配置
• Sourcegraph Cody: 通过OpenCtx桥接进行配置
• 任何MCP客户端: 使用流式HTTP传输

---

🔧 配置

环境变量

变量	必需	默认值	描述
LETTA_API_KEY	✅ 是	-	您从api.letta.com获取的Letta API密钥
LETTA_BASE_URL	否	https://api.letta.com	Letta API端点（用于自托管）
PORT	否	8000	Railway自动分配此端口
LETTA_TIMEOUT	否	60	请求超时时间（秒）
LETTA_MAX_RETRIES	否	3	失败请求的最大重试次数

Letta Cloud设置

1. 注册：在 letta.com 创建账户
2. 获取API密钥：访问 api.letta.com → 设置 → API密钥
3. 创建代理：使用Web界面创建您的第一个代理
4. 测试连接：使用letta_health_check工具验证

---

🛠️ 可用工具（20多个Letta函数）

🤖 代理管理

• letta_list_agents - 列出所有代理，支持分页和过滤
• letta_create_agent - 创建新的代理，带有记忆块和工具
• letta_get_agent - 获取详细的代理信息
• letta_update_agent - 更新代理配置（名称、描述、模型）
• letta_delete_agent - 安全删除代理，带确认

💬 对话

• letta_send_message - 发送消息给代理，支持流式传输
• letta_get_conversation_history - 获取聊天历史记录，支持分页
• letta_export_conversation - 导出对话（markdown、JSON、文本）

🧠 记忆管理

• letta_get_memory - 查看代理的所有记忆块
• letta_update_memory - 更新记忆块（人类、角色、自定义）
• letta_create_memory_block - 创建自定义记忆块
• letta_search_memory - 搜索代理的对话记忆

🔧 工具管理

• letta_list_tools - 列出所有可用工具，支持过滤
• letta_get_agent_tools - 查看特定代理附带的工具
• letta_attach_tool - 将工具添加到代理
• letta_detach_tool - 从代理移除工具

📊 监控与健康

• letta_health_check - 验证API连接和服务状态
• letta_get_usage_stats - 获取使用统计和分析

---

🏗️ 技术架构

Railway优化特性

• 流式HTTP传输：针对云部署优化，而非标准IO
• 连接池：维护持久连接以提高性能
• 自动扩展：Railway根据需求自动扩展
• 零停机部署：热重载，无连接丢失
• 内置监控：Railway仪表板显示指标和日志

性能优化

# 针对Railway云环境优化
- HTTP长连接
- 请求/响应压缩
- 带退避机制的智能重试逻辑
- 内存高效的JSON流式传输
- 自动连接池管理

传输比较

特性	标准IO（本地）	流式HTTP（Railway）
云部署	❌ 不支持	✅ 支持
负载均衡	❌ 不支持	✅ 自动
水平扩展	❌ 不支持	✅ 支持
健康监控	❌ 有限	✅ 完整
零停机部署	❌ 不支持	✅ 支持

---

💻 本地开发

快速本地设置

# 克隆仓库
git clone https://github.com/SNYCFIRE-CORE/letta-mcp-server-railway.git
cd letta-mcp-server-railway

# 安装依赖
pip install -e .

# 设置环境变量
export LETTA_API_KEY=your_api_key_here

# 本地运行
python -m letta_mcp_server_railway.server

本地测试

# 使用MCP Inspector测试
npx @modelcontextprotocol/inspector http://localhost:8000/mcp

# 或使用curl
curl -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}'

开发命令

# 运行测试
pytest tests/

# 格式化代码
black src/ tests/

# 类型检查
mypy src/

# 代码检查
ruff check src/

---

🔍 故障排除

常见问题

1. "连接被拒绝"错误

# 检查您的Railway应用是否正在运行
curl https://your-app.up.railway.app/health

# 验证Railway仪表板中的环境变量
# 确保LETTA_API_KEY正确设置

2. "无效API密钥"错误

# 直接测试您的Letta API密钥
curl -H "Authorization: Bearer your_api_key" https://api.letta.com/v1/agents

3. "超时"错误

# 在您的MCP客户端配置中增加超时时间
{
  "mcpServers": {
    "letta-railway": {
      "url": "https://your-app.up.railway.app/mcp",
      "transport": "streamable_http",
      "timeout": 300  // 增加到5分钟
    }
  }
}

4. Claude Desktop无法连接

• 在配置更改后重启Claude Desktop
• 使用JSON验证器检查配置文件语法
• 验证URL是否可以从浏览器访问

获取帮助

1. 查看Railway日志：在Railway仪表板中查看部署日志
2. 测试健康端点：访问 https://your-app.up.railway.app/health
3. 验证MCP端点：使用MCP Inspector测试
4. 社区支持：加入 Letta Discord
5. 报告问题：GitHub Issues

---

🚀 生产部署

Railway部署最佳实践

环境管理

# 生产环境变量
LETTA_API_KEY=your_production_api_key
LETTA_BASE_URL=https://api.letta.com
PORT=8000  # Railway自动管理此端口
LETTA_TIMEOUT=300
LETTA_MAX_RETRIES=5

健康监控

Railway提供了内置监控，但您还可以：

• 设置自定义健康检查
• 监控响应时间和错误率
• 配置停机警报

扩展配置

# railway.toml - 生产设置
[build]
builder = "DOCKERFILE"

[deploy]
restartPolicyType = "ON_FAILURE"

[[deploy.environmentVariables]]
name = "PORT"
value = "8000"

---

📖 资源

文档

• Letta文档 - 完整的Letta平台指南
• MCP规范 - 模型上下文协议标准
• Railway文档 - Railway平台指南
• FastMCP文档 - HTTP传输框架

社区与支持

• Letta Discord - 积极的社区支持
• MCP社区 - 协议开发
• Railway社区 - 部署支持
• GitHub Issues - 错误报告和功能

示例与教程

• Letta代理示例 - 示例代理配置
• MCP客户端集成 - 客户端设置指南
• Railway模板 - 部署模板

---

🤝 贡献

我们欢迎贡献，使Letta MCP Server Railway变得更好！

快速贡献指南

1. Fork 仓库
2. 创建 特性分支：git checkout -b feature/amazing-feature
3. 进行 修改并添加测试
4. 本地测试：pytest tests/
5. 提交 明确的消息：git commit -m "添加了惊人的功能"
6. 推送到 您的Fork：git push origin feature/amazing-feature
7. 提交 Pull Request

开发设置

# Fork并克隆您的Fork
git clone https://github.com/YOUR_USERNAME/letta-mcp-server-railway.git
cd letta-mcp-server-railway

# 安装开发依赖
pip install -e ".[dev]"

# 安装预提交钩子
pre-commit install

# 运行测试
pytest tests/ -v

我们需要帮助的地方

• 📖 文档改进
• 🧪 更多测试覆盖
• 🔧 Railway部署优化
• 🌐 多语言客户端示例
• 🐛 错误修复和性能改进

---

📜 许可证

MIT许可证 - 详情见 LICENSE。

---

🙏 致谢

由社区构建，以❤️实现无缝的AI代理部署。

特别感谢：

• Letta.ai 提供革命性的有状态代理
• Railway 提供卓越的部署平台
• Anthropic 领导MCP规范
• FastMCP 提供HTTP传输框架
• 所有贡献者 使这个项目成为可能

---

<p align="center"> <strong>🚂 在30秒内将Letta代理部署到云端 - Railway让这一切变得轻松。</strong> </p> <p align="center"> <a href="https://railway.app/new/template?template=https://github.com/SNYCFIRE-CORE/letta-mcp-server-railway"> <img src="https://railway.app/button.svg" alt="部署到 Railway"> </a> </p>