Skip to main content
The @atomicmemory/mcp-server package exposes AtomicMemory’s core memory operations as Model Context Protocol (MCP) tools. Any MCP-compatible agent host — including Claude Desktop, Cursor, custom runners, and programmatic clients — can call these tools to give its agents durable, semantic memory. The binary is named atomicmemory-mcp and communicates over stdio, which is the standard MCP transport.

​
Installation

Install globally with npm, or run on demand with npx: 
npm install -g @atomicmemory/mcp-server

# Or run on demand without a global install:
npx @atomicmemory/mcp-server
The MCP server requires Node.js 20 or later.
atomicmemory-mcp is the stdio protocol process for agent hosts. It is separate from atomicmemory, the interactive CLI. Do not confuse the two — they serve different roles and are installed as separate packages.

​
Exposed tools

The MCP server registers four tools that any connected agent can invoke:

memory_search

Semantic search over memories scoped to a user, namespace, or agent. Returns ranked results with relevance context.

memory_ingest

Persist a conversation turn or free-form text as durable memories. Extracts discrete facts from the content automatically.

memory_package

Assemble a context block from semantically relevant memories, respecting a caller-specified token budget. Ideal for system-prompt injection.

memory_list

Enumerate memories in scope. Useful for inspection, debugging, and building memory-management UIs.

​
Configuring the MCP server

Most agent hosts that support MCP accept a JSON configuration block that tells them how to launch the server process. The example below works for any host using the standard MCP server config format: 
{
  "mcpServers": {
    "atomicmemory": {
      "command": "npx",
      "args": ["-y", "@atomicmemory/mcp-server"],
      "env": {
        "ATOMICMEMORY_API_URL": "http://127.0.0.1:17350",
        "ATOMICMEMORY_API_KEY": "local-dev-key",
        "ATOMICMEMORY_PROVIDER": "atomicmemory",
        "ATOMICMEMORY_SCOPE_USER": "your-username"
      }
    }
  }
}
Replace your-username with the identifier you want all memories scoped to in this session.

​
Environment variables

All configuration is provided through environment variables. There are no flags — the process reads its config from the environment at startup.
​
ATOMICMEMORY_API_URL
string
default:"http://127.0.0.1:17350"
The base URL of your AtomicMemory Core service. Change this when running Core on a remote host or a non-default port.
​
ATOMICMEMORY_API_KEY
string
default:"local-dev-key"
The bearer token used to authenticate with Core. For local development the default value is accepted without configuration. Set this to a real secret in any shared or production environment.
​
ATOMICMEMORY_PROVIDER
string
default:"atomicmemory"
The memory provider backend. Accepted values: atomicmemory (default) or mem0.
​
ATOMICMEMORY_SCOPE_USER
string
The user identifier that scopes all memory operations for this server instance. At least one of the scope variables must be set — the server rejects scopeless requests.
​
ATOMICMEMORY_SCOPE_NAMESPACE
string
Optional namespace for further scoping memories within a user or agent context. Use this to separate memories by application, project, or environment.
​
ATOMICMEMORY_SCOPE_AGENT
string
Optional agent identifier. Set this when you want memories scoped to a specific agent rather than (or in addition to) a user.

​
Programmatic usage

If you are building a host or integration layer and need to start the MCP server from code, the package exposes two programmatic entry points: 
// Start the MCP server in-process
import { createMcpServer } from '@atomicmemory/mcp-server';

// Spawn the MCP server as a child process
import { spawnMcpServer } from '@atomicmemory/mcp-server/spawn';
These are useful for test harnesses, embedded agent runners, and custom host implementations that manage server lifecycle programmatically.

​
Using dedicated plugins instead

For Claude Code, Codex, and Cursor, you do not need to configure the MCP server manually. The dedicated plugins handle server lifecycle, scope binding, and skill injection automatically — and they integrate more deeply with each host’s context window and hook system.

Claude Code Plugin

Automatic lifecycle management and skill injection for Claude Code.

Cursor Plugin

Deep Cursor integration with automatic scope and hook configuration.
Use the manual MCP config above for any host not covered by a dedicated plugin, for custom runners, or when you need fine-grained control over scope and environment variables.