MemoAir MCP Server

MCP (Model Context Protocol) server for accessing MemoAir memories from Claude, Cursor, and other MCP-compatible clients.

Transport Options

The MCP server supports three transport modes:

| Transport | Use Case | Port | Endpoint | |-----------|----------|------|----------| | HTTP (default) | Remote clients (Cursor, Lovable, production) | 8000 | /mcp | | stdio | Local development (Claude Desktop direct) | N/A | N/A | | SSE (legacy) | Legacy remote clients | 8090 | /mcp |

Recommended: Use HTTP transport for production and remote access. It supports per-request X-User-ID headers, enabling multi-user scenarios.

Quick Start

Prerequisites

• MemoAir backend running on http://localhost:8080
• Node.js 20+

Installation

cd mcp-server
npm install
npm run build

Maintainer Release Check

Before publishing a new npm version, run:

npm run release:check

This verifies tests, rebuilds dist during pack via prepack, and shows the exact tarball contents that npm will publish. Confirm the package includes:

• memoair-mcp
• memoair-init
• memoair-connect
• dist/cli/connect.js
• dist/cli/installers/claude-code.js

Configuration by Client Type

HTTP-Enabled Clients (Cursor, Claude Code, Lovable, Windsurf)

For clients that support HTTP MCP transport natively, use the exact MCP URL shown in the MemoAir dashboard. Hosted MemoAir currently uses https://mcp-server.memoair.space/mcp.

{
  "mcpServers": {
    "memoair": {
      "url": "https://mcp-server.memoair.space/mcp",
      "headers": {
        "X-API-Key": "memoair_pk_your_project_key",
        "X-User-ID": "[email protected]"
      }
    }
  }
}

For local development:

{
  "mcpServers": {
    "memoair": {
      "url": "http://localhost:8000/mcp",
      "headers": {
        "X-API-Key": "memoair_pk_your_project_key",
        "X-User-ID": "[email protected]"
      }
    }
  }
}

Claude Desktop

For the smoothest setup, start MemoAir's local installer helper and let the dashboard install Claude Desktop for you:

npx -p memoair-mcp memoair-connect bridge

Open the MemoAir dashboard, choose Claude Desktop, and click install. The helper updates claude_desktop_config.json on your machine.

Fallback: direct local install command

npx -p memoair-mcp memoair-connect claude-desktop --mcp-url "https://mcp-server.memoair.space/mcp" --project-api-key "memoair_pk_your_project_key" --user-id "[email protected]"

Manual config

Claude Desktop doesn't support HTTP transport directly. Use mcp-remote as a bridge:

{
  "mcpServers": {
    "memoair": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp-server.memoair.space/mcp", "--header", "X-API-Key:${X_API_KEY}", "--header", "X-User-ID:${X_USER_ID}"],
      "env": {
        "X_API_KEY": "memoair_pk_your_project_key",
        "X_USER_ID": "[email protected]"
      }
    }
  }
}

Alternative: Direct stdio mode (local only)

For local development without network overhead:

{
  "mcpServers": {
    "memoair": {
      "command": "node",
      "args": ["/path/to/memoair/mcp-server/dist/index.js"],
      "env": {
        "MEMOAIR_API_BASE": "http://localhost:8080",
        "MEMOAIR_API_KEY": "memoair_pk_your_project_key",
        "MEMOAIR_USER_ID": "[email protected]"
      }
    }
  }
}

Claude Code

Claude Code supports native MCP installation via claude mcp add. MemoAir wraps that in a generated helper command:

npx -p memoair-mcp memoair-connect claude-code --mcp-url "https://mcp-server.memoair.space/mcp" --project-api-key "memoair_pk_your_project_key" --user-id "[email protected]" --scope local

This installs MemoAir into Claude Code's local MCP scope for the current project.

Multi-User Bot Integration

For company bots serving multiple end-users, vary X-User-ID per request:

// Each request can specify a different user
const config = {
  url: "https://mcp-server.memoair.space/mcp",
  headers: {
    "X-API-Key": "memoair_pk_company_project_key",
    "X-User-ID": dynamicEndUserId // Varies per request
  }
}

This pattern is ideal for:

• Slack/Discord bots with multiple users
• Customer support agents serving different customers
• Multi-tenant SaaS integrations

Available Tools

1. search_memories

Search through your saved memories using semantic search.

Parameters:

• query (required): Search query
• limit (optional): Maximum results to return (default: 10)
• view (optional): Filter by memory view (all, verified_facts, stable_preferences, working_context)

2. save_memory

Save a new memory to working memory (hippocampus).

Parameters:

• content (required): The memory content to save
• source_url (optional): URL where this originated
• source_title (optional): Title of the source
• image_url (optional): URL to an image
• description (optional): Description for screenshots

3. delete_memory

Delete a memory by its ID.

Parameters:

• id (required): The memory ID to delete

4. update_memory

Update an existing memory.

Parameters:

• id (required): The memory ID to update
• content (required): Updated content

5. analyze_query

Analyze information and automatically determine the best action (add, update, or delete).

Parameters:

• query (required): The information to analyze
• source_url (optional): Source URL
• source_title (optional): Source title

6. list_working_memory

List items in working memory by category.

Parameters:

• categories (optional): Array of categories (tab, clip, task, agent, chat)
• include_content (optional): Include full content (default: false)
• limit (optional): Max items per category (default: 10)

7. get_working_memory_context

Retrieve context from a specific working memory item.

Parameters:

• category (required): Category to search
• query (optional): Search query
• item_id (optional): Specific item ID
• limit (optional): Max items (default: 5)

Server Prompts

1. memory_assistant

Initialize as a proactive memory assistant that automatically searches and saves.

2. search_context

Search memories for a specific topic.

3. save_insight

Save an important insight with categorization.

See docs/SERVER_PROMPTS.md for detailed usage guide.

Environment Variables

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | MEMOAIR_TRANSPORT | No | stdio | Transport mode: http, stdio, sse | | PORT | No | 8000 | HTTP/SSE server port | | MEMOAIR_API_BASE | No | http://localhost:8080 | Backend URL | | MEMOAIR_API_KEY | Yes* | - | Project API key | | MEMOAIR_USER_ID | Yes* | local-user | User identifier |

*Required for stdio mode; for HTTP mode, pass via X-API-Key and X-User-ID headers.

Running the Server

Local Development (stdio)

npm run dev

HTTP Mode (production)

MEMOAIR_TRANSPORT=http PORT=8000 npm start

Docker

docker build -t memoair-mcp .
docker run -p 8000:8000 -e MEMOAIR_API_BASE=http://host.docker.internal:8080 memoair-mcp

Health Check

For HTTP/SSE transports:

curl http://localhost:8000/health
# Response: {"status":"healthy","service":"memoair-mcp","transport":"http"}

Working Memory TTL

Memories saved via MCP have a 24-hour sliding TTL:

• Initial TTL: 24 hours
• Extended on each tool call in the session
• Promotes active agent context, expires inactive items

Troubleshooting

1. Connection refused: Ensure MemoAir backend is running on port 8080
2. No memories found: Check that you have notes saved via the extension
3. MCP not working in Claude: Restart Claude Desktop after config changes
4. HTTP transport not working: Verify MEMOAIR_TRANSPORT=http is set
5. mcp-remote errors: Ensure npx is in PATH, try npm install -g mcp-remote