Skip to main content
Glama

Letta MCP Server

by oculairmedia

Letta MCP Server

A Model Context Protocol (MCP) server that provides comprehensive tools for agent management, memory operations, and integration with the Letta system. This server implements the full MCP specification including tools, prompts, and resources, with enhanced descriptions, output schemas, and behavioral annotations.

View on npm | View on GitHub

Features

  • 🤖 Agent Management - Create, modify, clone, and manage Letta agents
  • 🧠 Memory Operations - Handle memory blocks and passages
  • 🔧 Tool Integration - Attach and manage tools for agents with full MCP support
  • 💬 Prompts - Interactive wizards and assistants for common workflows
  • 📚 Resources - Access system information, documentation, and agent data
  • 🌐 Multiple Transports - HTTP, SSE, and stdio support
  • 🔗 MCP Server Integration - Integrate with other MCP servers
  • 📊 Enhanced Metadata - Output schemas and behavioral annotations for all tools
  • 📦 Docker Support - Easy deployment with Docker

Environment Configuration

Create a .env file with the following variables:

# Required LETTA_BASE_URL=https://your-letta-instance.com/v1 LETTA_PASSWORD=your-secure-password # Optional PORT=3001 NODE_ENV=production

Installation

Install from npm

# Global installation (recommended for CLI usage) npm install -g letta-mcp-server # Or local installation npm install letta-mcp-server

Use with Claude Desktop

After installing globally, add to your Claude Desktop configuration:

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

Quick Start with npm

# Install globally npm install -g letta-mcp-server # Set environment variables export LETTA_BASE_URL=https://your-letta-instance.com/v1 export LETTA_PASSWORD=your-secure-password # Run the server letta-mcp # stdio (for Claude Desktop) letta-mcp --http # HTTP transport letta-mcp --sse # SSE transport

Quick Setup

Option 1: Run from source

# Clone the repository git clone https://github.com/oculairmedia/letta-MCP-server.git cd letta-MCP-server # Install dependencies npm install # Development npm run dev # Default (stdio) transport npm run dev:sse # SSE transport npm run dev:http # HTTP transport (recommended) # Production npm run start # Default (stdio) transport npm run start:sse # SSE transport npm run start:http # HTTP transport (recommended)

Option 2: Run with Docker

Using the prebuilt image from GitHub Container Registry

Available tags:

  • latest - Latest stable release
  • 2.0.1, 2.0, 2 - Specific version tags
  • master - Latest master branch build
# Pull the latest image docker pull ghcr.io/oculairmedia/letta-mcp-server:latest # Run with environment variables 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 # Or use a specific version 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
Using 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
Building from source
# Clone and build locally 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

Option 3: Run with stdio for local MCP

# Create startup script chmod +x /opt/stacks/letta-MCP-server/start-mcp.sh # Add to Claude claude mcp add --transport stdio letta-tools "/opt/stacks/letta-MCP-server/start-mcp.sh"

Architecture

See the Architecture Documentation for detailed system diagrams and component relationships.

MCP Protocol Support

This server implements the full MCP specification with all three capabilities:

🔧 Tools

All tools include:

  • Enhanced Descriptions: Detailed explanations with use cases and best practices
  • Output Schemas: Structured response definitions for predictable outputs
  • Behavioral Annotations: Hints about tool behavior (readOnly, costLevel, executionTime, etc.)

💬 Prompts

Interactive prompts for common workflows:

  • letta_agent_wizard - Guided agent creation with memory and tool setup
  • letta_memory_optimizer - Analyze and optimize agent memory usage
  • letta_debug_assistant - Troubleshoot agent issues
  • letta_tool_config - Discover, attach, create, or audit tools
  • letta_migration - Export, import, upgrade, or clone agents

📚 Resources

Access system information and documentation:

  • letta://system/status - System health and version info
  • letta://system/models - Available LLM and embedding models
  • letta://agents/list - Overview of all agents
  • letta://tools/all/docs - Complete tool documentation with examples
  • letta://docs/mcp-integration - Integration guide
  • letta://docs/api-reference - API quick reference

Resource templates for dynamic content:

  • letta://agents/{agent_id}/config - Agent configuration
  • letta://agents/{agent_id}/memory/{block_id} - Memory block content
  • letta://tools/{tool_name}/docs - Individual tool documentation

Available Tools

Agent Management

ToolDescriptionAnnotations
create_agentCreate a new Letta agent💰 Medium cost, ⚡ Fast
list_agentsList all available agents👁️ Read-only, 💰 Low cost
prompt_agentSend a message to an agent💰 High cost, ⏱️ Variable time, 🔒 Rate limited
retrieve_agentGet agent details by ID👁️ Read-only, ⚡ Fast
get_agent_summaryGet agent summary information👁️ Read-only, ⚡ Fast
modify_agentUpdate an existing agent✏️ Modifies state, ⚡ Fast
delete_agentDelete an agent⚠️ Dangerous, 🗑️ Permanent
clone_agentClone an existing agent💰 Medium cost, ⏱️ Medium time
bulk_delete_agentsDelete multiple agents⚠️ Dangerous, 📦 Bulk operation
export_agentExport agent configuration and memory👁️ Read-only, ⚡ Fast, 📦 Full backup
import_agentImport agent from backup💰 High cost, ⏱️ Slow, ✏️ Creates state

Memory Management

ToolDescriptionAnnotations
list_memory_blocksList all memory blocks👁️ Read-only, ⚡ Fast
create_memory_blockCreate a new memory block✏️ Creates state, ⚡ Fast
read_memory_blockRead a memory block👁️ Read-only, ⚡ Fast
update_memory_blockUpdate a memory block✏️ Modifies state, ⚡ Fast
attach_memory_blockAttach memory to an agent✏️ Links resources, ⚡ Fast

Passage Management

ToolDescriptionAnnotations
list_passagesSearch archival memory👁️ Read-only, ⚡ Fast
create_passageCreate archival memory💰 Medium cost (embeddings), ⚡ Fast
modify_passageUpdate archival memory💰 Medium cost (re-embedding), ⚡ Fast
delete_passageDelete archival memory🗑️ Permanent, ⚡ Fast

Tool Management

ToolDescriptionAnnotations
list_agent_toolsList tools for an agent👁️ Read-only, ⚡ Fast
attach_toolAttach tools to an agent✏️ Modifies capabilities, ⚡ Fast
upload_toolUpload a custom tool🔒 Security: Executes code, ⚡ Fast
bulk_attach_tool_to_agentsAttach tool to multiple agents📦 Bulk operation, ⏱️ Slow

Model Management

ToolDescriptionAnnotations
list_llm_modelsList available LLM models👁️ Read-only, ⚡ Fast
list_embedding_modelsList available embedding models👁️ Read-only, ⚡ Fast

MCP Integration

ToolDescriptionAnnotations
list_mcp_serversList configured MCP servers👁️ Read-only, ⚡ Fast
list_mcp_tools_by_serverList tools from an MCP server👁️ Read-only, ⚡ Fast
add_mcp_tool_to_lettaImport MCP tool to Letta✏️ Creates tool, ⚡ Fast

Prompt Tools

ToolDescriptionAnnotations
list_promptsList available prompt templates👁️ Read-only, ⚡ Fast
use_promptExecute a prompt template💰 Variable cost, ⏱️ Variable time

Directory Structure

  • src/index.js - Main entry point
  • src/core/ - Core server functionality
  • src/handlers/ - Prompt and resource handlers
  • src/examples/ - Example prompts and resources
  • src/tools/ - Tool implementations organized by category:
    • agents/ - Agent management tools
    • memory/ - Memory block tools
    • passages/ - Passage management tools
    • tools/ - Tool attachment and management
    • mcp/ - MCP server integration tools
    • models/ - Model listing tools
    • enhanced-descriptions.js - Detailed tool descriptions
    • output-schemas.js - Structured output definitions
    • annotations.js - Behavioral hints
  • src/transports/ - Server transport implementations

Transport Protocols

The server supports three transport protocols:

  1. HTTP (Recommended) - Streamable HTTP transport with full duplex communication
    • Endpoint: http://your-server:3001/mcp
    • Best for production use and remote connections
    • Supports health checks at /health
  2. SSE (Server-Sent Events) - Real-time event streaming
    • Endpoint: http://your-server:3001/sse
    • Good for unidirectional server-to-client updates
  3. stdio - Standard input/output
    • Direct process communication
    • Best for local development and Claude integration

Configuration with MCP Settings

Add the server to your mcp_settings.json:

"letta": { "command": "node", "args": [ "--no-warnings", "--experimental-modules", "path/to/letta-server/src/index.js" ], "env": { "LETTA_BASE_URL": "https://your-letta-instance.com", "LETTA_PASSWORD": "yourPassword" }, "disabled": false, "alwaysAllow": [ "upload_tool", "attach_tool", "list_agents", "list_memory_blocks" ], "timeout": 300 }

For remote instances with HTTP transport (recommended):

"remote_letta_tools": { "url": "http://your-server:3001/mcp", "transport": "http", "disabled": false, "alwaysAllow": [ "attach_tool", "list_agents", "list_tools", "get_agent" ], "timeout": 120 }

Docker Operations

# View container logs docker logs -f letta-mcp # Stop the container docker stop letta-mcp # Update to latest version docker pull ghcr.io/oculairmedia/letta-mcp-server:latest docker stop letta-mcp docker rm letta-mcp docker run -d -p 3001:3001 -e PORT=3001 -e NODE_ENV=production --name letta-mcp ghcr.io/oculairmedia/letta-mcp-server:latest

Troubleshooting

Common Issues

  1. Connection refused errors
    • Ensure the server is running and accessible
    • Check firewall settings for port 3001
    • Verify the correct transport protocol is being used
  2. Authentication failures
    • Verify LETTA_BASE_URL includes /v1 suffix
    • Check LETTA_PASSWORD is correct
    • Ensure environment variables are loaded
  3. Tool execution timeouts
    • Increase timeout values in MCP configuration
    • Check network latency for remote connections
    • Consider using HTTP transport for better reliability

Health Check

The HTTP transport provides a health endpoint:

curl http://your-server:3001/health

Response:

{ "status": "healthy", "transport": "streamable_http", "protocol_version": "2025-06-18", "sessions": 0, "uptime": 12345.678 }

Development

Testing

# Run tests npm test # Run tests with coverage npm run test:coverage # Run linter npm run lint

Contributing

We welcome contributions! Please see our Contributing Guide for details on:

  • Development setup
  • Code style and standards
  • Adding new tools
  • Testing requirements
  • Pull request process

Security

For security vulnerabilities, please see our Security Policy.

License

MIT License - see LICENSE file for details

Deploy Server
A
security – no known vulnerabilities
A
license - permissive license
A
quality - confirmed to work

hybrid server

The server is able to function both locally and remotely, depending on the configuration or use case.

An MCP server implementation that enables interaction with the Letta API for managing agents, memory blocks, and tools in the Letta system.

  1. Quick Setup
    1. Option 1: Run with Node.js
    2. Option 2: Run with Docker
  2. Directory Structure
    1. Available Tools
      1. Agent Management
      2. Memory Management
      3. Tool Management
      4. Additional Tools
    2. Docker Operations
      1. Configuration with MCP Settings

        Related MCP Servers

        • A
          security
          A
          license
          A
          quality
          A Model Context Protocol server that enables AI assistants to interact with Linear project management systems, allowing users to retrieve, create, and update issues, projects, and teams through natural language.
          Last updated -
          42
          1,070
          101
          MIT License
          • Apple
        • A
          security
          F
          license
          A
          quality
          An MCP server that enables LLMs to interact with Agent-to-Agent (A2A) protocol compatible agents, allowing for sending messages, tracking tasks, and receiving streaming responses.
          Last updated -
          5
          25
        • Atlaofficial

          A
          security
          A
          license
          A
          quality
          The Atla MCP Server provides a standardized interface for LLMs to interact with the Atla API for state-of-the-art LLMJ evaluation.
          Last updated -
          2
          16
          MIT License
          • Apple
          • Linux
        • A
          security
          A
          license
          A
          quality
          A meta-MCP server that manages and aggregates other MCP servers, enabling LLMs to dynamically extend their own capabilities by searching for, adding, and configuring tool servers.
          Last updated -
          16
          58
          AGPL 3.0
          • Linux
          • Apple

        View all related MCP servers

        MCP directory API

        We provide all the information about MCP servers via our MCP API.

        curl -X GET 'https://glama.ai/api/mcp/v1/servers/oculairmedia/Letta-MCP-server'

        If you have feedback or need assistance with the MCP directory API, please join our Discord server