MemMachine MCP Server

A Model Context Protocol (MCP) server that exposes the MemMachine memory-management API as rich tools for LLMs. It connects to your MemMachine deployment (default http://10.0.1.18:8080) and surfaces every memory endpoint as a callable MCP tool.

Features

• npx-friendly CLI (npx memmachine-mcp) for stdio transports
• Tool coverage for adding, searching, and deleting memories plus session discovery, health, and metrics
• Configurable base URL and headers through environment variables
• Strongly typed validation with Zod to keep tool inputs predictable

Installation & Usage

# Install locally (optional)
npm install -g memmachine-mcp-server

# Or run ad-hoc via npx
npx memmachine-mcp

Environment Variables

| Variable | Description | Default | | --- | --- | --- | | MEMMACHINE_BASE_URL | Base HTTP URL for the MemMachine API | http://10.0.1.18:8080 | | MEMMACHINE_API_KEY | Optional bearer token sent as Authorization: Bearer <token> | unset | | MEMMACHINE_TIMEOUT_MS | HTTP request timeout in milliseconds | 10000 | | MEMMACHINE_USER_AGENT | Custom UA header for outbound requests | memmachine-mcp-server/<version> | | MEMMACHINE_DEFAULT_USER | Default user-id header (comma-separated for multiples). Also set via --memmachine-user / --user | unset |

Set these before launching the server (or configure them inside your MCP host application) to point at a different MemMachine instance.

Tip: you can pass --memmachine-user <name> (or --user <name>) when launching the server to override the default user without touching your environment. This is useful for MCP configurations that already support per-server arguments. Additional header defaults are available via MEMMACHINE_DEFAULT_GROUP_ID, MEMMACHINE_DEFAULT_SESSION_ID, and MEMMACHINE_DEFAULT_AGENT_IDS (comma-separated).

Tools Exposed

| Tool Name | Purpose | | --- | --- | | memmachine.add-memory | Add a memory episode to both episodic and profile stores | | memmachine.add-episodic-memory | Add an episode only to the episodic store | | memmachine.add-profile-memory | Add an episode only to the profile store | | memmachine.delete-session-data | Delete all data for the header-derived session scope | | memmachine.search-memories | Search both episodic and profile memories concurrently | | memmachine.search-episodic | Search episodic memories only | | memmachine.search-profile | Search profile memories only | | memmachine.list-sessions | List every known session | | memmachine.list-user-sessions | List sessions for a specific userId | | memmachine.list-group-sessions | List sessions for a specific groupId | | memmachine.list-agent-sessions | List sessions for a specific agentId | | memmachine.health-check | Fetch the /health heartbeat | | memmachine.metrics | Fetch the /metrics payload |

Each memory-focused tool accepts optional sessionHeaders (group, session, user, agent) so you can scope operations precisely the same way the REST API expects.

All tools accept friendly shorthand inputs: provide raw strings for things like sessionHeaders ("sessionHeaders": "session-123"), search queries ("query": "latest stand-up"), or ID filters ("args": "user-42"). The server normalizes those into the richer request objects the MemMachine API requires.

Development

npm install
npm run dev       # tsx watch mode
npm run build     # emit dist/

Before publishing to npm, run npm test (if you add tests) and npm run build. The prepare script automatically compiles TypeScript so the package ships pre-built.

MCP Host Integration

Point your MCP-compatible client (e.g., Claude Desktop, Cursor, VS Code MCP integrations) at the executable:

"servers": {
  "memmachine": {
    "command": "npx",
    "args": ["memmachine-mcp"],
    "env": {
      "MEMMACHINE_BASE_URL": "https://your-domain:8080",
      "MEMMACHINE_API_KEY": "..."
    }
  }
}

Once connected, use the listed tools to manage MemMachine memories directly from your LLM workflow.