Letta MCP Server

Letta MCP 服务

一个面向 Letta AI 的高性能模型上下文协议（MCP）服务，使用 Rust 和 TurboMCP 框架构建。

功能

• 7 个整合工具：使用判别器模式涵盖 103 项操作
• 高性能：使用 Rust，内存占用约为 10-30MB，启动时间小于 500ms，通过 tokio::join! 和 buffer_unordered 并行扇出
• 双传输方式：stdio（Claude Desktop、Cursor 等）和 HTTP（生产部署）
• 响应大小优化：响应大小减少 68-96%，提高大模型上下文效率
• 类型收窄的 Schema：使用具体的 object/array 类型，并为每个参数提供描述（不使用通用的 Value 参数）
• 多平台支持：macOS、Linux、Windows（x64 和 arm64）
• 兼容 Letta 0.16.x：归档、对话、MCP 服务 v2
• 符合 MCP 2025-11-25：支持 SSE 的可流式 HTTP 传输
• 编译时路由：通过 TurboMCP v3 宏实现工具分派，运行时开销为零

快速开始

npm（推荐）

npm install -g letta-mcp-server

系统会自动安装适用于你平台的二进制文件。

平台	软件包
macOS Intel	letta-mcp-darwin-x64
macOS Apple Silicon	letta-mcp-darwin-arm64
Linux x64	letta-mcp-linux-x64
Linux arm64	letta-mcp-linux-arm64
Windows x64	letta-mcp-windows-x64

Docker

docker pull ghcr.io/oculairmedia/letta-mcp-server-rust:rust-latest

docker run -d \
  -p 6507:6507 \
  -e LETTA_BASE_URL=http://your-letta-instance:8283 \
  -e LETTA_PASSWORD=your-password \
  -e TRANSPORT=http \
  --name letta-mcp \
  ghcr.io/oculairmedia/letta-mcp-server-rust:rust-latest

Docker Compose

services:
  letta-mcp:
    image: ghcr.io/oculairmedia/letta-mcp-server-rust:rust-latest
    container_name: letta-mcp
    restart: unless-stopped
    ports:
      - '6507:6507'
    environment:
      LETTA_BASE_URL: ${LETTA_BASE_URL}
      LETTA_PASSWORD: ${LETTA_PASSWORD}
      TRANSPORT: http
      PORT: 6507
      RUST_LOG: info
    env_file:
      - .env
    healthcheck:
      test: ['CMD-SHELL', "timeout 1 bash -c '</dev/tcp/localhost/6507' || exit 1"]
      interval: 30s
      timeout: 10s
      retries: 3

环境变量

变量	必需	默认值	描述
LETTA_BASE_URL	是	—	Letta API URL（例如 http://localhost:8283）
LETTA_PASSWORD	是	—	Letta API 密码
TRANSPORT	否	stdio	传输模式：stdio 或 http
PORT	否	6507	HTTP 端口（当 TRANSPORT=http 时）
RUST_LOG	否	info	日志级别：debug、info、warn、error
RUST_BACKTRACE	否	0	启用回溯（0 或 1）
LETTA_MCP_MAX_VALUE_LEN	否	500	块、段落和搜索值的最大字符数
LETTA_MCP_CORE_MEMORY_PREVIEW_LEN	否	200	核心记忆预览的最大字符数

可用工具

该服务提供 7 个整合工具，包含 103 项操作：

工具	操作数	描述
letta_agent_advanced	28	Agent 生命周期、消息、对话、上下文、导出/导入
letta_memory_unified	24	核心记忆、块、归档段落、归档、搜索
letta_tool_manager	13	工具增删改查、附加/分离、批量操作
letta_source_manager	15	数据源、文件、段落、附件
letta_job_monitor	4	任务跟踪、取消、活动监控
letta_file_folder_ops	8	文件会话、文件夹管理
letta_mcp_ops	11	MCP 服务生命周期、工具发现、支持 v2 API

工具操作

letta_agent_advanced（28 项操作）

list, create, get, update, delete, search, list_tools, send_message,
export, import, clone, get_config, bulk_delete, context, reset_messages,
summarize, stream, async_message, cancel_message, preview_payload,
search_messages, get_message, count, list_conversations,
get_conversation, send_conversation_message, cancel_conversation,
compact_conversation

letta_memory_unified（24 项操作）

get_core_memory, update_core_memory, get_block_by_label, list_blocks,
create_block, get_block, update_block, attach_block, detach_block,
list_agents_using_block, search_archival, list_passages, create_passage,
update_passage, delete_passage, search_memory, list_archives,
get_archive, create_archive, update_archive, delete_archive,
attach_archive, detach_archive, list_agents_using_archive

letta_tool_manager（13 项操作）

list, get, create, update, delete, upsert, attach, detach, bulk_attach,
generate_from_prompt, generate_schema, run_from_source, add_base_tools

letta_source_manager（15 项操作）

list, get, create, update, delete, count, attach, detach, list_attached,
upload, delete_files, list_files, list_folders, get_folder_contents,
list_agents_using

letta_job_monitor（4 个操作）

list, get, cancel, list_active

letta_file_folder_ops（8 个操作）

list_files, open_file, close_file, close_all_files, list_folders,
attach_folder, detach_folder, list_agents_in_folder

letta_mcp_ops（11 个操作）

add, update, delete, test, connect, resync, list_servers, list_tools,
register_tool, execute, attach_mcp_server

响应大小优化

Rust 实现针对大模型上下文效率进行了显著的响应大小优化：

操作	优化	大小缩减
Agent 列表	默认分页（15 项）、摘要模式	68-85%
工具列表	默认分页（25 项）、截断描述	70-90%
记忆块	列表模式下排除较大的字段	60-80%
源列表	摘要模式、分页	75-95%

分页

所有列表操作均支持分页：

{
  "operation": "list",
  "pagination": {
    "limit": 25,
    "offset": 0
  }
}

摘要模式与完整模式

列表操作默认返回摘要数据。使用带有特定 ID 的 get 操作可获取完整详情：

// Summary (default for list)
{
  "id": "agent-123",
  "name": "My Agent",
  "model": "gpt-4",
  "tool_count": 5
}

// Full (with get operation)
{
  "id": "agent-123",
  "name": "My Agent",
  "model": "gpt-4",
  "system_prompt": "...",
  "tools": [...],
  "memory_blocks": [...]
}

MCP 客户端配置

Claude Desktop

{
  "mcpServers": {
    "letta": {
      "command": "letta-mcp",
      "env": {
        "LETTA_BASE_URL": "http://localhost:8283",
        "LETTA_PASSWORD": "your-password"
      }
    }
  }
}

Cursor / Windsurf

{
  "mcpServers": {
    "letta": {
      "command": "letta-mcp",
      "env": {
        "LETTA_BASE_URL": "http://localhost:8283",
        "LETTA_PASSWORD": "your-password"
      }
    }
  }
}

OpenCode（HTTP）

{
  "mcp": {
    "letta-mcp": {
      "type": "remote",
      "url": "http://localhost:6507/mcp",
      "enabled": true
    }
  }
}

从源代码构建

前置条件

• Rust nightly（支持 edition 2024）- 通过 rustup 安装
• Docker（可选，用于容器化构建）

本地构建

git clone https://github.com/oculairmedia/Letta-MCP-server.git
cd Letta-MCP-server

cargo build --release

LETTA_BASE_URL=http://your-letta:8283 \
LETTA_PASSWORD=your-password \
./target/release/letta-server

进行本地开发时，Rust 二进制文件也会自动加载仓库级 .env 文件，因此无需手动导出变量即可运行 cargo run -p letta-server。

Docker 构建

docker build -f Dockerfile.rust -t letta-mcp .

docker run -d \
  -p 6507:6507 \
  -e LETTA_BASE_URL=http://your-letta:8283 \
  -e LETTA_PASSWORD=your-password \
  -e TRANSPORT=http \
  letta-mcp

架构

letta-server/
├── src/
│   ├── main.rs                        # Entry point, transport selection
│   ├── lib.rs                         # Server init, compile-time tool registration
│   └── tools/
│       ├── mod.rs                     # Tool module exports
│       ├── response_utils.rs          # Unified ToolResponse, pagination helpers
│       ├── validation_utils.rs        # require_field, require_id, sdk_err
│       ├── id_utils.rs               # ID parsing utilities
│       ├── agent_advanced/            # Agent operations (28 ops)
│       │   ├── crud.rs               #   list, create, get, update, delete, search
│       │   ├── messaging.rs           #   send_message, stream, async, preview
│       │   ├── conversations.rs       #   list, get, send, cancel, compact
│       │   └── management.rs          #   export, import, clone, config, bulk_delete
│       ├── memory_unified/            # Memory operations (24 ops)
│       │   ├── core.rs               #   get/update core memory
│       │   ├── blocks.rs             #   block CRUD, attach/detach
│       │   ├── passages.rs           #   archival passage CRUD
│       │   ├── archives.rs           #   archive CRUD, attach/detach
│       │   └── search.rs             #   search_archival, search_memory
│       ├── tool_manager.rs            # Tool operations (13 ops)
│       ├── source_manager.rs          # Source operations (15 ops)
│       ├── job_monitor.rs             # Job operations (4 ops)
│       ├── file_folder_ops.rs         # File/folder operations (8 ops)
│       └── mcp_ops.rs                # MCP server v2 operations (11 ops)
├── tests/                             # Integration tests
└── Cargo.toml

主要依赖项

• TurboMCP v3 -- MCP 框架，支持编译时路由和可流式 HTTP
• letta-rs -- 随附的 Rust Letta API 客户端（0.16.x）
• Tokio -- 异步运行时
• Futures -- 流组合器（用于并行扇出的 buffer_unordered）
• Serde -- 序列化/反序列化

故障排除

连接被拒绝

1. 确保服务正在运行：docker ps | grep letta-mcp
2. 检查日志：docker logs letta-mcp
3. 验证端口是否可访问：curl http://localhost:6507/mcp

身份验证错误

1. 确认 LETTA_BASE_URL 指向你的 Letta 实例
2. 检查 LETTA_PASSWORD 或 LETTA_API_TOKEN 是否正确
3. 确保可从容器访问 Letta 服务

找不到工具

1. 通过 MCP 列出可用工具：tools/list
2. 确认使用了正确的操作名称（例如，使用 list 而非 list_agents）

日志

# View server logs
docker logs -f letta-mcp

# Enable debug logging
RUST_LOG=debug letta-mcp

贡献

1. Fork 此仓库
2. 创建功能分支：git checkout -b feature/my-feature
3. 进行更改并添加测试
4. 运行测试：cargo test
5. 提交拉取请求

许可证

MIT 许可证 - 详情请参阅 LICENSE 文件。

相关项目

• Letta - Letta AI 框架
• TurboMCP - Rust 的 MCP 框架
• Model Context Protocol - MCP 规范