Installing MCP Memory Service on GNU/Linux

TL;DR:

MCP Memory Service is a powerful memory management system that integrates with Claude Desktop and Claude Code. This tutorial covers the complete installation process specifically for GNU/Linux systems (Ubuntu 18.04+, Debian, and derivatives), including prerequisites, installation steps, configuration, and troubleshooting.

Prerequisites

Before installing MCP Memory Service, ensure your system meets these requirements:

System Requirements

Operating System: Ubuntu 18.04 or newer, Debian 10+, or equivalent GNU/Linux distributions
Python: Version 3.10 or newer (3.11+ recommended for optimal performance)
Memory: Minimum 4GB RAM (8GB+ recommended for better performance)
Storage: At least 2GB free disk space
Architecture: x86_64 (AMD64) or ARM64

Required Dependencies

The installer will handle most dependencies automatically, but you’ll need basic system packages:

sudo apt update
sudo apt install python3.10 python3.10-venv python3-pip git curl

Installation

Method 1: Universal Installer (Recommended)

The fastest way to install MCP Memory Service on GNU/Linux:

# Clone the repository
git clone https://github.com/doobidoo/mcp-memory-service.git
cd mcp-memory-service

# Run the universal installer
python3 install.py

The installer will:

Detect your GNU/Linux distribution
Install optimal dependencies
Configure SQLite-vec backend (recommended for Linux)
Set up environment variables
Generate a secure API key
Optionally install as a system service

Method 2: Manual Installation

If you prefer manual control:

# Install system dependencies
sudo apt update
sudo apt install python3.10 python3.10-venv python3-pip git build-essential

# Clone and setup
git clone https://github.com/doobidoo/mcp-memory-service.git
cd mcp-memory-service

# Create virtual environment (optional but recommended)
python3 -m venv venv
source venv/bin/activate

# Install Python dependencies
pip install -e .

Advanced Installation Options

GPU Acceleration (Optional)

For systems with NVIDIA GPUs:

python3 install.py --cuda

For AMD GPUs with ROCm support:

python3 install.py --rocm

System Service Installation

To run MCP Memory Service as a background service that starts automatically:

# Install as system service
sudo python3 install.py --service

# Or install manually after regular installation
sudo python3 scripts/install_service.py

Docker Service Installation

For containerized deployment using Docker:

Prerequisites

Ensure Docker and Docker Compose are installed:

# Install Docker
sudo apt update
sudo apt install docker.io docker-compose
sudo systemctl start docker
sudo systemctl enable docker

# Add user to docker group (optional, avoids sudo)
sudo usermod -aG docker $USER
# Logout and login again for group changes to take effect

Quick Docker Setup

For MCP Protocol integration (Claude Desktop/VS Code):

# Clone the repository (if not already done)
git clone https://github.com/doobidoo/mcp-memory-service.git
cd mcp-memory-service

# Start with Docker Compose
docker-compose up -d

For HTTP API access (REST API/Web Dashboard):

# Start with HTTP API enabled
docker-compose -f docker-compose.http.yml up -d

# Verify the service is running
curl http://localhost:8000/api/health

Docker Configuration

Create a .env file in the project directory for customization:

# Storage backend (SQLite-vec recommended for Docker)
MCP_MEMORY_STORAGE_BACKEND=sqlite_vec

# HTTP API settings
MCP_HTTP_ENABLED=true
MCP_HTTP_PORT=8000

# Security (generate a secure key)
MCP_API_KEY=your-secure-api-key-here

# Optional: Enable HTTPS
MCP_HTTPS_ENABLED=true

Docker Service Management

# Start the service
docker-compose up -d

# Stop the service
docker-compose down

# View logs
docker-compose logs -f

# Restart the service
docker-compose restart

# Update the service
docker-compose pull && docker-compose up -d

Docker with GPU Support

For GPU acceleration in Docker:

# NVIDIA GPU
docker-compose -f docker-compose.gpu.yml up -d

# AMD GPU (ROCm)
docker-compose -f docker-compose.rocm.yml up -d

Configuration

Storage Backend Selection

MCP Memory Service supports multiple storage backends. For GNU/Linux, SQLite-vec is recommended:

# Set environment variable
export MCP_MEMORY_STORAGE_BACKEND=sqlite_vec

Other options:

ChromaDB: For multi-client setups
Cloudflare: For production deployments

Essential Environment Variables

Create a .env file or export these variables:

# Storage configuration
export MCP_MEMORY_STORAGE_BACKEND=sqlite_vec

# HTTP API (optional)
export MCP_HTTP_ENABLED=true
export MCP_HTTP_PORT=8000

# Security
export MCP_API_KEY="$(openssl rand -base64 32)"

# Performance tuning
export MAX_RESULTS_PER_QUERY=10
export SIMILARITY_THRESHOLD=0.7

Configuration Files

Configuration is stored in ~/.mcp_memory_service/:

Service config: service_config.json
Logs: logs/ directory
Data: Platform-specific storage location

Service Management

Systemd Service Commands

# Start the service
systemctl --user start mcp-memory

# Stop the service
systemctl --user stop mcp-memory

# Check status
systemctl --user status mcp-memory

# Restart the service
systemctl --user restart mcp-memory

# Enable auto-start on boot
systemctl --user enable mcp-memory

# View logs
journalctl --user -u mcp-memory -f

Manual Service Management

If not using systemd:

# Start manually
uv run memory server

# Or with HTTP API
uv run memory server --http

Verification and Testing

Basic Functionality Test

# Verify environment
python3 scripts/verify_environment.py

# Test memory operations
uv run memory store "Test memory for GNU/Linux installation"
uv run memory recall "test installation"
uv run memory health

HTTP API Testing (if enabled)

# Health check
curl -k https://localhost:8000/api/health

# Store a memory via API
curl -k -X POST https://localhost:8000/api/memories \
  -H "Content-Type: application/json" \
  -d '{"content": "API test memory from GNU/Linux"}'

# Search memories
curl -k -X POST https://localhost:8000/api/search \
  -H "Content-Type: application/json" \
  -d '{"query": "GNU/Linux"}'

Integration with Claude

Claude Desktop Integration

After installation, configure Claude Desktop by editing ~/.claude/config.json:

{
  "mcpServers": {
    "memory": {
      "command": "uv",
      "args": ["--directory", "/path/to/mcp-memory-service", "run", "memory", "server"],
      "env": {
        "MCP_MEMORY_STORAGE_BACKEND": "sqlite_vec"
      }
    }
  }
}

Replace /path/to/mcp-memory-service with your actual installation path.

Claude Code Integration

For developers using Claude Code:

# Install with Claude Code support
python3 install.py --claude-code

# Install memory awareness hooks
python3 scripts/install_claude_hooks.py

Troubleshooting

Common Issues

Permission Errors During Installation:

# Use virtual environment
python3 -m venv venv
source venv/bin/activate
python3 install.py

Port Already in Use:

# Change the default port
export MCP_HTTP_PORT=8001

Service Won’t Start:

# Check systemd logs
journalctl --user -u mcp-memory -n 50

# Verify configuration
python3 scripts/verify_environment.py

Python Version Issues:

# Check Python version
python3 --version

# Install specific version if needed
sudo apt install python3.11 python3.11-venv

Dependency Installation Failures:

# Update pip and reinstall
pip install --upgrade pip
pip install --force-reinstall -e .

Performance Optimization

For better performance on GNU/Linux:

# Enable mDNS service discovery
export MCP_MDNS_ENABLED=true

# Adjust similarity threshold
export SIMILARITY_THRESHOLD=0.8

# Increase results per query
export MAX_RESULTS_PER_QUERY=20

Next Steps

After successful installation:

Test Integration: Verify MCP Memory Service works with Claude Desktop
Explore Features: Try different storage backends and configurations
Monitor Performance: Use the health check endpoint regularly
Backup Data: Set up regular backups of your memory data
Update Regularly: Keep MCP Memory Service updated with git pull && pip install -e .

Getting Help

Documentation: MCP Memory Service Wiki
Issues: GitHub Issues
Discussions: GitHub Discussions

This tutorial focuses exclusively on GNU/Linux installations while covering all essential aspects from the official guide.

Twitter Facebook LinkedIn

Installing MCP Memory Service on GNU/Linux

Jan Peter Alexander

Prerequisites

System Requirements

Required Dependencies

Installation

Method 1: Universal Installer (Recommended)

Method 2: Manual Installation

Advanced Installation Options

GPU Acceleration (Optional)

System Service Installation

Docker Service Installation

Prerequisites

Quick Docker Setup

Docker Configuration

Docker Service Management

Docker with GPU Support

Configuration

Storage Backend Selection

Essential Environment Variables

Configuration Files

Service Management

Systemd Service Commands

Manual Service Management

Verification and Testing

Basic Functionality Test

HTTP API Testing (if enabled)

Integration with Claude

Claude Desktop Integration

Claude Code Integration

Troubleshooting

Common Issues

Performance Optimization

Next Steps

Getting Help

You May Also Enjoy

Compiling Memory MCP Server Without CUDA

A Guide to GitHub Spec Kit Commands and MCP Integration

My Mantra for QWEN Code

My Experience Using GitHub Spec Kit with OpenCode and Qwen Code CLI