Letta MCP Server

Letta MCP Server

Rust と TurboMCP フレームワークで構築された、Letta AI 向けの高性能な Model Context Protocol（MCP）サーバーです。

特長

• 7 つの統合ツール：識別子パターンを使用して 103 の操作を網羅
• 高パフォーマンス：Rust を採用し、メモリ使用量は約 10～30 MB、起動時間は 500 ms 未満、tokio::join! と buffer_unordered による並列ファンアウトを実現
• 2 種類のトランスポート：stdio（Claude Desktop、Cursor など）および HTTP（本番環境へのデプロイ）
• レスポンスサイズの最適化：LLM のコンテキスト効率を高めるため、レスポンスサイズを 68～96％削減
• 型を絞り込んだスキーマ：パラメーターごとの説明を備えた具体的な 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	コアメモリのプレビューの最大文字数

利用可能なツール

サーバーは 103 の操作を備えた 7 つの統合ツールを提供します。

ツール	操作数	説明
letta_agent_advanced	28	エージェントのライフサイクル、メッセージング、会話、コンテキスト、エクスポート／インポート
letta_memory_unified	24	コアメモリ、ブロック、アーカイブパッセージ、アーカイブ、検索
letta_tool_manager	13	ツールの CRUD、アタッチ／デタッチ、一括操作
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 実装では、LLM のコンテキスト効率を高めるため、レスポンスサイズを大幅に最適化しています。

操作	最適化	サイズ削減率
エージェント一覧	デフォルトのページネーション（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 -- コンパイル時ルーティングとストリーミング可能な HTTP に対応した MCP フレームワーク
• 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_agents ではなく list）

ログ

# View server logs
docker logs -f letta-mcp

# Enable debug logging
RUST_LOG=debug letta-mcp

貢献

1. リポジトリをフォークします
2. 機能ブランチを作成します：git checkout -b feature/my-feature
3. 変更を加え、テストを追加します
4. テストを実行します：cargo test
5. プルリクエストを送信します

ライセンス

MIT License - 詳細は LICENSE ファイルを参照してください。

関連プロジェクト

• Letta - Letta AI フレームワーク
• TurboMCP - Rust 用 MCP フレームワーク
• Model Context Protocol - MCP 仕様