Ampelos

A modular MCP (Model Context Protocol) service framework designed to provide stateful, persistent services to Letta AI agents.

Installation

Run this command in your terminal to add the MCP server to Claude Code.

Run in terminal:

View docs

Command

claude mcp add --transport stdio tanner-caffrey-ampelos node src/server.js \
  --env LETTA_TOKEN="your-let ta-token (if using self-hosted Letta)" \
  --env DATABASE_URL="sqlite:storage/ampelos.db (default path)" \
  --env LETTA_SERVER_URL="http://localhost:8283 (or your Letta server URL)" \
  --env LETTA_CLOUD_API_KEY="your Letta Cloud API key (if using Letta Cloud)" \
  --env LETTA_CLOUD_PROJECT_ID="your Letta Cloud project ID"

How to use

Ampelos is a modular MCP server that provides stateful, persistent services to Letta AI agents through a pluggable module system. It exposes an HTTP API and a chat web frontend (optional) to interact with modular tools and services such as memory, tooling, and Letta integrations. With Ampelos you can run multiple modules (tools and services) that can persist per-agent state, leverage SQLite storage, and communicate through the MCP protocol for seamless agent integration. The architecture supports lazy/eager initialization, hot-reloadable configuration, and inter-service dependencies, making it suitable for building configurable agent ecosystems that scale with Letta."

How to install

Prerequisites:

Node.js >= 18.0.0
npm >= 8.0.0
Letta Server (self-hosted) or Letta Cloud account

Installation steps:

Clone the repository: git clone https://github.com/tanner-caffrey/Ampelos.git cd Ampelos
Install dependencies: npm install
Copy environment template and configure: cp .env.example .env

Edit .env with your Letta and database configuration
Run in development mode: npm run dev
(Optional) Run with the chat web frontend: npm run dev:all
Access the server: MCP Server: http://localhost:3005 Chat Web UI: http://localhost:5173 (when using dev:all)

Additional notes

Tips:

Ampelos uses SQLite in WAL mode for performance; ensure the database file path is writable by the running process.
Environment variables in .env (or via mcp_config.env) control Letta integration and module behavior; review .env.example for available options.
The modular architecture supports adding new modules under src/modules; modules can expose tools (interactive commands) and services (background tasks).
For production, consider configuring Letta endpoints, securing the API, and validating configurations with the included Zod-powered config validation.
If you encounter port conflicts, adjust the MCP server port (default 3005) and frontend port (default 5173) in your environment or start scripts.

Related MCP Servers

after-effects

217

MCP Server for Adobe After Effects. Enables remote control (compositions, text, shapes, solids, properties) via the Model Context Protocol using ExtendScript.

mcp

🤖 A Model Context Protocol (MCP) library for use with Agentic chat bots

mobile

A Model Context Protocol (MCP) server that provides mobile automation capabilities.

docmole

Dig through any documentation with AI - MCP server for Claude, Cursor, and other AI assistants

obsidian

MCP server for Obsidian vault management - enables Claude and other AI assistants to read, write, search, and organize your notes

civitai

A Model Context Protocol server for browsing and discovering AI models on Civitai