![GitHub Sponsors](https://github.com/sponsors/MarcelRoozekrans)

<h1 align="center">MemoryLens MCP</h1>

<p align="center"> On-demand .NET memory profiling with concrete, AI-actionable code fix suggestions — wraps JetBrains dotMemory with a heuristic-based rule engine. </p>

---

Hosted deployment

A hosted deployment is available on Fronteir AI.

Quick Start

npx (any MCP client)

{
  "mcpServers": {
    "memorylens": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "memorylens-mcp"]
    }
  }
}

The npm package ships no server code — it is a launcher that installs the MemoryLens.Mcp .NET global tool at a matching version and execs it, so the .NET 10 SDK must be on PATH. Subsequent starts skip the install entirely and work offline.

VS Code / Visual Studio (via dnx)

Add to your MCP settings (.vscode/mcp.json or VS settings):

{
  "servers": {
    "memorylens": {
      "type": "stdio",
      "command": "dnx",
      "args": ["MemoryLens.Mcp", "--yes"]
    }
  }
}

Claude Code Plugin

claude install gh:MarcelRoozekrans/memorylens-mcp

.NET Global Tool

dotnet tool install -g MemoryLens.Mcp

Docker

docker build -t memorylens-mcp .
docker run -i --rm --pid=host --cap-add=SYS_PTRACE \
  -v "$PWD:/workspace" -v memorylens-tools:/root/.memorylens memorylens-mcp

Profiling from a container needs ptrace and the host PID namespace, and on Docker Desktop that namespace is the Linux VM rather than your desktop — see docs/docker.md before choosing this route.

Prerequisites

.NET 10 SDK or later
JetBrains dotMemory CLI (see below for installation options)

dotMemory CLI Installation

MemoryLens MCP automatically downloads and caches the JetBrains dotMemory CLI on first use via the ensure_dotmemory tool — no manual installation required on supported platforms.

Supported Platforms (auto-download)

| Platform | Architecture | |---|---| | Windows | x64, x86, ARM64 | | Linux (glibc) | x64, ARM64, ARM | | Linux (musl) | x64, ARM64 | | macOS | x64 (Intel), ARM64 (Apple Silicon) |

Cache Location

Downloaded binaries are cached at ~/.memorylens/tools/dotmemory/{version}/. Old versions are not auto-removed — delete the directory manually to free disk space.

Unsupported Platforms

Platforms not listed above (e.g. FreeBSD, Linux x86) cannot use auto-download. Set DOTMEMORY_PATH to point to an existing dotMemory CLI executable:

export DOTMEMORY_PATH="/path/to/dotMemory.sh"   # Linux/macOS
set DOTMEMORY_PATH=C:\path\to\dotMemory.exe      # Windows

Find dotMemory CLI in JetBrains Toolbox:

Linux: ~/.local/share/JetBrains/Toolbox/apps/rider/tools/profiler/dotMemory.sh
Windows: %LOCALAPPDATA%\JetBrains\Toolbox\apps\rider\tools\profiler\dotMemory.exe

Manual Fallback Discovery

If auto-download is unavailable, MemoryLens MCP falls back through these discovery modes in order:

DOTMEMORY_PATH environment variable — explicit path to the CLI executable
System PATH — searches for dotMemory.sh / dotMemory (Linux/macOS) or dotMemory.exe (Windows)
Local .NET tool manifest — dotnet tool install dotnet-dotmemory --local
Global .NET tool — dotnet tool install -g dotnet-dotmemory (legacy fallback)

Error Scenarios

| Error | Cause | Fix | |---|---|---| | Platform '...' is not supported | Unsupported OS/arch | Set DOTMEMORY_PATH | | Network/download failure | No internet / NuGet unreachable | Set DOTMEMORY_PATH or retry ensure_dotmemory | | chmod +x failed | Read-only filesystem | Set DOTMEMORY_PATH to a writable location | | dotMemory CLI not found | All discovery modes failed | Run ensure_dotmemory or set DOTMEMORY_PATH |

Available MCP Tools

| Tool | Description | |------|-------------| | ensure_dotmemory | Downloads and verifies the JetBrains dotMemory CLI tool is available | | list_processes | Lists running .NET processes available for profiling. Discovers them from their diagnostic IPC endpoints, so it works before ensure_dotmemory | | snapshot | Captures a single memory snapshot of a target process | | compare_snapshots | Captures two snapshots with configurable delay and compares them | | analyze | Runs the rule engine against a captured snapshot and returns findings | | get_rules | Lists all available analysis rules with their metadata |

Built-in Rules

| ID | Severity | Category | Description | |----|----------|----------|-------------| | ML001 | critical | leak | Event handler leak detected | | ML002 | critical | leak | Static collection growing unbounded | | ML003 | high | leak | Disposable object not disposed | | ML004 | high | fragmentation | Large Object Heap fragmentation | | ML005 | medium | retention | Object retained longer than expected | | ML006 | medium | allocation | Excessive allocations in hot path | | ML007 | medium | retention | Closure retaining unexpected references | | ML008 | low | allocation | Array/list resizing without capacity hint | | ML009 | low | pattern | Finalizer without Dispose pattern | | ML010 | low | pattern | String interning opportunity |

Configuration

Create a .memorylens.json file in your project root to customize rule behavior:

{
  "rules": {
    "ML001": { "enabled": true, "severity": "critical" },
    "ML002": { "enabled": true, "severity": "critical" },
    "ML003": { "enabled": true, "severity": "high" },
    "ML004": { "enabled": true, "severity": "high" },
    "ML005": { "enabled": true, "severity": "medium" },
    "ML006": { "enabled": true, "severity": "medium" },
    "ML007": { "enabled": true, "severity": "medium" },
    "ML008": { "enabled": true, "severity": "low" },
    "ML009": { "enabled": true, "severity": "low" },
    "ML010": { "enabled": true, "severity": "low" }
  }
}

Usage Examples

Single Snapshot

Capture a memory snapshot of a running process to inspect current memory state:

> /memorylens
> Take a snapshot of my running API (PID 12345)

Claude will call ensure_dotmemory, then snapshot with the target PID, then analyze the result and present findings ordered by severity.

Before/After Comparison

Detect memory growth by comparing two snapshots taken with a delay:

> /memorylens
> Check if my app has a memory leak — compare before and after processing 1000 requests

Claude will call compare_snapshots with a configurable wait period, then analyze the diff to identify objects that grew between snapshots.

License

MIT

memorylens-mcp