莱塔-MCP-服务器

Name: 莱塔-MCP-服务器
Author: oculairmedia

作者：oculairmedia48 星标更新：2025-11-17

安装使用来源：spider==github.com

项目介绍

Letta MCP 服务器

一个模型上下文协议（MCP）服务器，提供全面的代理管理、内存操作工具以及与Letta系统的集成。此服务器实现了完整的MCP规范，包括工具、提示和资源，并带有增强的描述、输出模式和行为注释。

在npm上查看 | 在GitHub上查看

功能

🤖 代理管理 - 创建、修改、克隆和管理Letta代理
🧠 内存操作 - 处理内存块和段落
🔧 工具集成 - 附带并管理具有完整MCP支持的代理工具
💬 提示 - 常见工作流程的交互式向导和助手
📚 资源 - 访问系统信息、文档和代理数据
🌐 多种传输方式 - 支持HTTP、SSE和stdio
🔗 MCP服务器集成 - 与其他MCP服务器集成
📊 增强元数据 - 所有工具的输出模式和行为注释
📦 Docker支持 - 使用Docker轻松部署

环境配置

创建一个包含以下变量的.env文件：

# 必需
LETTA_BASE_URL=https://your-letta-instance.com/v1
LETTA_PASSWORD=your-secure-password

# 可选
PORT=3001
NODE_ENV=production

安装

从npm安装

# 全局安装（推荐用于CLI使用）
npm install -g letta-mcp-server

# 或本地安装
npm install letta-mcp-server

与Claude Desktop一起使用

全局安装后，在Claude Desktop配置中添加：

{
  "mcpServers": {
    "letta": {
      "command": "letta-mcp",
      "args": [],
      "env": {
        "LETTA_BASE_URL": "https://your-letta-instance.com/v1",
        "LETTA_PASSWORD": "your-secure-password"
      }
    }
  }
}

使用npm快速启动

# 全局安装
npm install -g letta-mcp-server

# 设置环境变量
export LETTA_BASE_URL=https://your-letta-instance.com/v1
export LETTA_PASSWORD=your-secure-password

# 运行服务器
letta-mcp              # stdio（用于Claude Desktop）
letta-mcp --http       # HTTP传输
letta-mcp --sse        # SSE传输

实现选项

本仓库提供了三种不同的实现的Letta MCP服务器，允许您根据使用情况选择最佳选项：

🔵 经典独立工具（master分支）

分支： master

原始实现，每个API端点都有独立的工具。

最适合：

喜欢独立、专注工具的用户
兼容现有集成
细粒度的工具选择和控制
一次学习Letta API的一个操作

Docker镜像：

# 最新的master分支构建
docker pull ghcr.io/oculairmedia/letta-mcp-server:master

功能：

70多个独立工具，每个处理一个特定的操作
直接映射到Letta API端点
简单、直白的工具名称
完整的MCP协议支持（工具、提示、资源）
多种传输协议（HTTP、SSE、stdio）

🟢 Node.js整合工具（推荐给大多数用户）

分支： nodejs-consolidated-tools

现代实现，使用鉴别器模式的7个整合工具。

最适合：

生产部署
Claude Desktop集成
npm包消费者
想要更少但功能更多的团队

Docker镜像：

# 最新稳定版本
docker pull ghcr.io/oculairmedia/letta-mcp-server:latest

# 特定版本
docker pull ghcr.io/oculairmedia/letta-mcp-server:2.0.1

# 开发分支
docker pull ghcr.io/[...]

功能：

7个整合工具覆盖87个操作
93%的官方@letta-ai/letta-client SDK覆盖率
鉴别器模式（使用operation参数）
增强的错误处理和验证
完整的MCP协议支持（工具、提示、资源）
全面的测试套件和文档

🦀 Rust实现（性能聚焦的替代方案）

分支： rust-implementation

使用Rust和TurboMCP框架构建的高性能实现。

最适合：

资源受限环境
极高的性能要求
低内存占用需求
熟悉Rust的团队

Docker镜像：

# 最新的Rust构建
docker pull ghcr.io/oculairmedia/letta-mcp-server-rust:rust-latest

# 开发分支
docker pull ghcr.io/oculairmedia/letta-mcp-server-rust:rust-implementation

功能：

同样的7个整合工具，完全的功能一致性
基于TurboMCP框架的MCP协议
编译时类型安全和验证
更低的内存使用和更快的执行速度
多架构Docker构建（amd64, arm64）

对比

特性	经典（master）	Node.js整合	Rust
工具数量	70+独立	7个整合	7个整合
API模式	每个端点一个工具	鉴别器模式	鉴别器模式
成熟度	✅ 原始	✅ 生产就绪	🟡 稳定，较新
性能	良好	良好	卓越
内存使用	~50-100MB	~50-100MB	~10-30MB
启动时间	~1-2秒	~1-2秒	~100-500毫秒
SDK集成	直接API调用	93%官方SDK	自定义API客户端
类型安全	运行时验证	TypeScript（运行时）	Rust（编译时）
包管理器	npm	npm	Docker/Cargo
使用场景	简单、专注	生产、功能丰富	性能关键

如何选择实现

如果使用经典（master）：

您喜欢独立、单一用途的工具
您已经在使用原始实现
您想要简单、直白的工具名称
您正在学习Letta API

如果使用Node.js整合：

您需要一个经过战斗考验、生产就绪的解决方案
您想要较少但功能丰富的工具
您正在使用npm包或Claude Desktop
您想要SDK驱动的可靠性和类型安全性

如果使用Rust：

您需要最大性能
您在资源受限环境中运行（边缘、嵌入式）
您偏好编译时的安全保证
您熟悉基于Docker的部署

所有三种实现都提供相同的功能和MCP协议合规性。您可以随时在它们之间切换而不改变您的Letta实例配置。

快速设置

选项1：从源代码运行

# 克隆仓库
git clone https://github.com/oculairmedia/letta-MCP-server.git
cd letta-MCP-server

# 安装依赖
npm install

# 开发
npm run dev         # 默认（stdio）传输
npm run dev:sse     # SSE传输
npm run dev:http    # HTTP传输（推荐）

# 生产
npm run start       # 默认（stdio）传输
npm run start:sse   # SSE传输
npm run start:http  # HTTP传输（推荐）

选项2：使用Docker运行

使用来自GitHub容器注册表的预构建镜像

可用标签：

latest - 最新的稳定版本
2.0.1, 2.0, 2 - 特定版本标签
master - 最新的master分支构建

# 拉取最新镜像
docker pull ghcr.io/oculairmedia/letta-mcp-server:latest

# 使用环境变量运行
docker run -d \
  -p 3001:3001 \
  -e LETTA_BASE_URL=https://your-letta-instance.com/v1 \
  -e LETTA_PASSWORD=your-secure-password \
  -e PORT=3001 \
  -e NODE_ENV=production \
  --name letta-mcp \
  ghcr.io/oculairmedia/letta-mcp-server:latest

# 或使用特定版本
docker run -d \
  -p 3001:3001 \
  -e LETTA_BASE_URL=https://your-letta-instance.com/v1 \
  -e LETTA_PASSWORD=your-secure-password \
  --name letta-mcp \
  ghcr.io/oculairmedia/letta-mcp-server:2.0.1

使用Docker Compose

version: '3.8'
services:
  letta-mcp:
    image: ghcr.io/oculairmedia/letta-mcp-server:latest
    container_name: letta-mcp
    ports:
      - "3001:3001"
    environment:
      - LETTA_BASE_URL=https://your-letta-instance.com/v1
      - LETTA_PASSWORD=your-secure-password
      - PORT=3001
      - NODE_ENV=production
    restart: unless-stopped

从源代码构建

# 克隆并本地构建
git clone https://github.com/oculairmedia/letta-MCP-server.git
cd letta-MCP-server
docker build -t letta-mcp-server .
docker run -d -p 3001:3001 --env-file .env --name letta-mcp letta-mcp-server

选项3：使用stdio进行本地MCP

# 创建启动脚本
chmod +x /opt/stacks/letta-MCP-server/start-mcp.sh

# 添加到Claude
claude mcp add --transport stdio letta-tools "/opt/stacks/letta-MCP-server/start-mcp.sh"

架构

参阅架构文档以获取详细的系统图和组件关系。

MCP协议支持

此服务器实现了完整的MCP规范，包括所有三个能力：

🔧 工具

所有工具包括：

增强描述：带有使用案例和最佳实践的详细解释
输出模式：结构化的响应定义，确保可预测的输出
行为注释：关于工具行为的提示（readOnly, costLevel, executionTime等）

💬 提示

常见工作流程的交互式提示：

letta_agent_wizard - 带有记忆和工具设置的引导代理创建
letta_memory_optimizer - 分析和优化代理内存使用
letta_debug_assistant - 解决代理问题
letta_tool_config - 发现、附加、创建或审核工具
letta_migration - 导出、导入、升级或克隆代理

📚 资源

访问系统信息和文档：

letta://system/status - 系统健康和版本信息
letta://system/models - 可用的LLM和嵌入模型
letta://agents/list - 所有代理的概览
letta://tools/all/docs - 包含示例的完整工具文档
letta://docs/mcp-integration - 集成指南
letta://docs/api-reference - API快速参考

资源模板用于动态内容：

letta://agents/{agent_id}/config - 代理配置
letta://agents/{agent_id}/memory/{block_id} - 内存块内容
letta://tools/{tool_name}/docs - 单个工具文档

可用工具

代理管理

工具	描述	注释
`create_agent`	创建一个新的Letta代理	💰 中等成本，⚡ 快速
`list_agents`	列出所有可用代理	👁️ 只读，💰 低成本
`prompt_agent`	向代理发送消息	💰 高成本，⏱️ 变量时间，🔒 速率限制
`retrieve_agent`	根据ID获取代理详情	👁️ 只读，⚡ 快速
`get_agent_summary`	获取代理摘要信息	👁️ 只读，⚡ 快速
`modify_agent`	更新现有代理	✏️ 修改状态，⚡ 快速
`delete_agent`	删除代理	⚠️ 危险，🗑️ 永久
`clone_agent`	克隆现有代理	💰 中等成本，⏱️ 中等时间
`bulk_delete_agents`	删除多个代理	⚠️ 危险，📦 批量操作
`export_agent`	导出代理配置和内存	👁️ 只读，⚡ 快速，📦 完全备份
`import_agent`	从备份导入代理	💰 高成本，⏱️ 慢，✏️ 创建状态

内存管理

工具	描述	注释
`list_memory_blocks`	列出所有内存块	👁️ 只读，⚡ 快速
`create_memory_block`	创建新的内存块	✏️ 创建状态，⚡ 快速
`read_memory_block`	读取内存块	👁️ 只读，⚡ 快速
`update_memory_block`	更新内存块	✏️ 修改状态，⚡ 快速
`attach_memory_block`	将内存附加到代理	✏️ 链接资源，⚡ 快速

段落管理

工具	描述	注释
`list_passages`	搜索归档内存	👁️ 只读，⚡ 快速
`create_passage`	创建归档内存	💰 中等成本（嵌入），⚡ 快速
`modify_passage`	更新归档内存	💰 中等成本（重新嵌入），⚡ 快速
`delete_passage`	删除归档内存	🗑️ 永久，⚡ 快速

工具管理

工具	描述	注释
`list_agent_tools`	列出代理的工具	👁️ 只读，⚡ 快速
`attach_tool`	将工具附加到代理	✏️ 修改能力，⚡ 快速
`upload_tool`	上传自定义工具	🔒 安全：执行代码，⚡ 快速
`bulk_attach_tool_to_agents`	将工具附加到多个代理	📦 批量操作，⏱️ 慢

模型管理

工具	描述	注释
`list_llm_models`	列出可用的LLM模型	👁️ 只读，⚡ 快速
`list_embedding_models`	列出可用的嵌入模型	👁️ 只读，⚡ 快速

MCP集成

工具	描述	注释
`list_mcp_servers`	列出已配置的MCP服务器	👁️ 只读，⚡ 快速
`list_mcp_tools_by_server`	列出MCP服务器上的工具	👁️ 只读，⚡ 快速
`add_mcp_tool_to_letta`	将MCP工具导入Letta	✏️ 创建工具，⚡ 快速

提示工具

工具	描述	注释
`list_prompts`	列出可用的提示模板	👁️ 只读，⚡ 快速
`use_prompt`	执行提示模板	💰 变量成本，⏱️ 变量时间

目录结构

src/index.js - 主入口点
src/core/ - 核心服务器功能
src/handlers/ - 提示和资源处理器
src/examples/ - 示例提示和资源
src/tools/ - 按类别组织的工具实现：
- agents/ - 代理管理工具
- memory/ - 内存块工具
- passages/ - 段落管理工具
- tools/ - 工具附加和管理
- mcp/ - MCP服务器集成工具
- models/ - 模型列表工具
- enhanced-descriptions.js - 详细的工具描述
- output-schemas.js - 结构化的输出定义
- annotations.js - 行为提示
src/transports/ - 服务器传输实现

传输协议

服务器支持三种传输协议：

HTTP（推荐） - 具有全双工通信的流式HTTP传输
- 端点：`http://your