Letta MCP Server Railway

🚀 莱塔MCP服务器铁路版

莱塔MCP服务器的云优化HTTP传输版本，可在30秒内部署到Railway平台。它是一个通用的MCP服务器，通过可流式传输的HTTP协议，将任何AI客户端连接到莱塔.ai强大的有状态代理，实现无缝的云部署。

🚀 快速部署到Railway

前提条件

• 从 api.letta.com 获取 莱塔API密钥（提供免费套餐）
• 拥有 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桌面版（ADE集成）

将以下内容添加到Claude桌面版配置文件中：

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检查器测试

使用MCP检查器测试你的部署：

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传输协议

🔧 配置

环境变量

莱塔云设置

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

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

🤖 代理管理

• 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传输：与标准输入输出相比，更适合云部署
• 连接池：维护持久连接以提高性能
• 自动扩展：Railway根据需求自动扩展
• 零停机部署：热重载且不丢失连接
• 内置监控：Railway仪表盘显示指标和日志

性能优化

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

传输方式比较

💻 本地开发

快速本地设置

# 克隆仓库
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检查器测试
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密钥”错误

# 直接测试你的莱塔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桌面版无法连接

• 配置更改后重启Claude桌面版
• 使用JSON验证器检查配置文件语法
• 验证URL是否可从你的浏览器访问

获取帮助

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

🚀 生产环境部署

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"

📖 资源

文档

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

社区与支持

• 莱塔Discord - 活跃的社区支持
• MCP社区 - 协议开发
• Railway社区 - 部署支持
• GitHub问题 - 错误报告和功能请求

示例与教程

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

🤝 贡献代码

我们欢迎大家贡献代码，让莱塔MCP服务器铁路版变得更好！

快速贡献指南

1. 分叉 仓库
2. 创建 功能分支：git checkout -b feature/amazing-feature
3. 进行 修改并添加测试
4. 本地测试：pytest tests/
5. 提交 清晰的提交信息：git commit -m "Add amazing feature"
6. 推送 到你的分叉仓库：git push origin feature/amazing-feature
7. 提交 拉取请求

开发环境设置

# 分叉并克隆你的分叉仓库
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代理的无缝部署。

特别感谢：

• 莱塔.ai 提供革命性的有状态代理
• Railway 提供出色的部署平台
• Anthropic 在MCP规范方面的领导地位
• FastMCP 提供HTTP传输框架
• 所有贡献者 让这个项目成为可能

🚂 在30秒内将莱塔代理部署到云端 - Railway让部署变得轻松。