neuroloom-mcp

MCP server that gives AI coding agents persistent memory via the Neuroloom knowledge graph API.

Install via pip

Requires Python 3.12+

pip install neuroloom-mcp
neuroloom-mcp install-plugin

Then restart Claude Code. The plugin and MCP server are configured together. Set your API key with /plugins configure neuroloom in Claude Code.

To upgrade:

pip install --upgrade neuroloom-mcp
neuroloom-mcp install-plugin --force

Hosted (Cloud) Connection

The Neuroloom MCP server is available as a hosted service — no local installation required.

Public endpoint: https://mcp.neuroloom.dev/mcp

Prerequisites

You need a Neuroloom API key. Create one at app.neuroloom.dev/settings/api-keys.

Claude Code

Create .mcp.json in your project root (the directory where you run Claude Code):

{
  "mcpServers": {
    "neuroloom": {
      "type": "http",
      "url": "https://mcp.neuroloom.dev/mcp",
      "headers": {
        "Authorization": "Bearer nl_your_api_key_here"
      }
    }
  }
}

Other MCP Clients

Any MCP client that supports HTTP (streamable HTTP) transport can connect using the url transport type and the Authorization header shown above.

Claude Desktop: Claude Desktop currently supports only the stdio transport. To use Neuroloom with Claude Desktop, follow the local stdio setup instructions below.

Verifying Your Connection

Check MCP server connectivity (unauthenticated):

curl https://mcp.neuroloom.dev/health

Expected response: {"status": "ok", "version": "0.1.0"} with HTTP 200.

Validate your API key against the Neuroloom API directly:

curl -H "Authorization: Token nl_your_api_key_here" https://api.neuroloom.dev/api/v1/workspaces/

HTTP 200 confirms the key is valid.

Note: MCP clients send Authorization: Bearer <key>; the Neuroloom API uses Authorization: Token <key>. The MCP server translates between the two schemes automatically.

Troubleshooting

OAuth Compatibility Layer

The server implements GET /.well-known/oauth-protected-resource as specified by RFC 9728. Some MCP clients (including newer versions of Claude Code) probe this endpoint before connecting to determine whether they need to start an OAuth authorization flow.

The handler returns an empty authorization_servers array, which signals to the client that no OAuth flow is needed — authentication is handled via the Authorization: Bearer <key> header that operators and developers already configure.

The implementation lives in neuroloom_mcp/server.py (oauth_protected_resource_handler). The route is registered without authentication middleware so the discovery probe is always reachable, even before a valid API key is presented.

Local Development (stdio)

For local use or Claude Desktop, install and run the MCP server as a stdio process.

Requires uv (Python package manager).

cd mcp && uv sync

Required environment variables

# MEMORIES_API_URL=https://api.neuroloom.dev  (default, override for local dev)
MEMORIES_API_TOKEN=your_api_key_here
MEMORIES_WORKSPACE_ID=your_workspace_id_here

Claude Code (stdio)

Add to your project's .mcp.json:

{
  "mcpServers": {
    "neuroloom": {
      "type": "stdio",
      "command": "uv",
      "args": ["--directory", "/path/to/neuroloom/mcp", "run", "neuroloom-mcp"],
      "env": {
        "MEMORIES_API_TOKEN": "your_api_key_here",
        "MEMORIES_WORKSPACE_ID": "your_workspace_id_here"
      }
    }
  }
}

Replace /path/to/neuroloom/mcp with the absolute path to the mcp/ directory in your local clone.

Documentation

Full setup guide and configuration reference: https://neuroloom.dev/docs