Overview

Memalot MCP Server is a lightweight server component for detecting, profiling, and diagnosing Python memory leaks. It exposes a simple HTTP API that lets you capture heap snapshots, sample or trace allocations, and compare historical snapshots to pinpoint objects that grow over time. The server is intended to run alongside your application — in development, staging, or production — so you can trigger profiling and gather evidence without restarting processes or attaching debuggers.

Using a dedicated MCP (Memalot Control Plane) server centralizes memory investigation: engineers can request snapshots from running services, collect traces of allocation hotspots, and analyze differences to find leaking code paths. This makes it easier to reproduce, triage, and fix leaks faster than ad-hoc sampling or manual heap inspection.

Features

Capture heap snapshots from running Python processes (tracemalloc-powered)
Start/stop lightweight allocation sampling and more detailed tracing
Compare snapshots to highlight growing object types and allocation sites
HTTP API for programmatic control and automation (curl/CI integration)
CLI client for one-off captures and local development
Configurable bind address, authentication token, and logging
Designed for low overhead to be safe for production use when sampling is enabled

Installation / Configuration

Install from PyPI (if published) or from the repository:

# From PyPI (if available)
pip install memalot

# From GitHub source
git clone https://github.com/nfergu/memalot.git
cd memalot
python -m pip install -e .

Start the MCP server (example CLI):

# default bind to localhost:8080
memalot-mcp-server --bind 127.0.0.1 --port 8080 --auth-token YOUR_TOKEN

Or run the module directly:

python -m memalot.mcp.server --bind 0.0.0.0 --port 9000 --auth-token s3cr3t

Environment-based configuration example (exported variables are read by the server):

export MEMALOT_BIND=0.0.0.0
export MEMALOT_PORT=9000
export MEMALOT_AUTH_TOKEN=s3cr3t
export MEMALOT_LOG_LEVEL=info
memalot-mcp-server

A minimal YAML configuration file (if supported):

bind: 127.0.0.1
port: 8080
auth_token: YOUR_TOKEN
log_level: info
snapshot_dir: /var/lib/memalot/snapshots

Security note: bind to localhost or secure access via network rules when running in production. Use an auth token or network authentication to avoid exposing sensitive heap data.

Available Tools

CLI: memalot-mcp-server and client helpers for capturing and downloading snapshots
HTTP API: endpoints to trigger snapshots, start/stop tracing, and compare results
Snapshot storage: configurable directory for saving snapshots and comparison outputs
Integration hooks: call the server API from tests, monitoring, or CI to detect regressions
Export formats: snapshot files suitable for local analysis with tracemalloc-compatible viewers or Memalot’s analysis tools

API Endpoints (quick reference)

Endpoint	Method	Description
/health	GET	Server health check
/snapshot	POST	Trigger heap snapshot capture; returns snapshot id
/snapshot/{id}	GET	Download snapshot file by id
/trace	POST	Start allocation tracing (optional parameters: duration, sample_rate)
/trace/{id}/stop	POST	Stop tracing and return trace id/file
/compare	POST	Compare two snapshots (params: base_id, new_id)
/allocations	GET	List recent allocation hotspots (top N)

Example: request a new heap snapshot with curl

curl -X POST "http://127.0.0.1:8080/snapshot" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"pid": 12345, "description": "after-deploy"}'

Download a snapshot:

curl -H "Authorization: Bearer YOUR_TOKEN" \
  http://127.0.0.1:8080/snapshot/<snapshot-id> --output snapshot1.dump

Compare two snapshots:

curl -X POST "http://127.0.0.1:8080/compare" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"base_id":"snap-2026-04-01", "new_id":"snap-2026-04-02"}'

Use Cases

Web application leak investigation: When memory of a Django/Flask app grows across requests, trigger snapshots before and after noisy endpoints to identify leaked object types and allocation sites. Use compare to get a short list of suspect call sites.
Long-running worker processes: Attach the MCP server to Celery or background workers and periodically sample allocations to detect growth patterns without stopping the worker.
Production hotfix triage: Collect a quick snapshot from production and download it to a local environment for deeper offline analysis, enabling faster diagnosis while minimizing production impact.
CI regression detection: Integrate snapshot capture or allocation hotspot checks into CI to fail builds when the number of retained objects or memory usage for a test suite increases significantly.
Systematic root-cause hunting: Use trace mode to capture stack traces for allocations in a specific time window (e.g., around a known spike) to find exact code paths responsible.

Tips and Best Practices

Prefer sampling mode for continuous production monitoring; use full tracing only on short, controlled windows.
Keep snapshots in a dedicated directory with rotation to avoid filling disk space.
Use authenticated access and network controls — heap snapshots may contain sensitive application data.
Combine snapshot comparisons with code diffs and deploy timestamps to correlate leaks with recent changes.

For more details, consult the repository README and examples in the project’s examples/ directory

Memalot MCP Server for Python Memory Leak Detection