Memos MCP Server

A Model Context Protocol (MCP) server for Memos - a self-hosted memo hub. This server enables AI assistants to create, search, and update memos through the Memos API.

Features

• Create memos with content, visibility settings, and location data
• Search memos by text query, tag, visibility, or state
• Get individual memos by ID
• Update memos - edit content, visibility, pin status, or archive

Requirements

• Bun 1.0+ (runs TypeScript natively, no build step required)
• A running Memos instance
• Personal Access Token from your Memos account

Installation

The package is published on npm and requires Bun to run (TypeScript executed natively):

bunx memos-mcp

Or install globally:

bun add -g memos-mcp

Configuration

The server requires two environment variables:

| Variable | Description | Example | | -------------------- | -------------------------------- | --------------------------- | | MEMOS_URL | Your Memos instance URL | https://memos.example.com | | MEMOS_ACCESS_TOKEN | Personal Access Token from Memos | eyJhbGciOiJIUzI1... |

Getting an Access Token

1. Log into your Memos instance
2. Go to Settings → My Account
3. Create a new Personal Access Token
4. Copy the token (it's only shown once)

Usage

Running the Server

MEMOS_URL=https://memos.example.com MEMOS_ACCESS_TOKEN=your-token bun run src/index.ts

OpenCode Configuration

Add to your opencode.json (or opencode.jsonc):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "memos": {
      "type": "local",
      "command": ["bunx", "memos-mcp"],
      "enabled": true,
      "environment": {
        "MEMOS_URL": "https://your-memos-instance.com",
        "MEMOS_ACCESS_TOKEN": "{env:MEMOS_ACCESS_TOKEN}"
      }
    }
  }
}

You can also use environment variables directly:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "memos": {
      "type": "local",
      "command": ["bunx", "memos-mcp"],
      "enabled": true,
      "environment": {
        "MEMOS_URL": "{env:MEMOS_URL}",
        "MEMOS_ACCESS_TOKEN": "{env:MEMOS_ACCESS_TOKEN}"
      }
    }
  }
}

Then use memos tools in your prompts:

Create a memo with today's meeting notes. use memos

Claude Desktop Configuration

Add to your Claude Desktop MCP configuration (requires Bun installed):

{
  "mcpServers": {
    "memos": {
      "command": "bunx",
      "args": ["memos-mcp"],
      "env": {
        "MEMOS_URL": "https://your-memos-instance.com",
        "MEMOS_ACCESS_TOKEN": "your-access-token-here"
      }
    }
  }
}

Available Tools

create_memo

Create a new memo.

| Parameter | Type | Required | Description | | ------------ | ------ | -------- | -------------------------------------------------------- | | content | string | Yes | Memo content (supports Markdown) | | visibility | string | No | PRIVATE, PROTECTED, or PUBLIC (default: PRIVATE) | | location | object | No | Location with placeholder, latitude, longitude |

search_memos

Search and list memos. Returns up to 100 words per memo as a snippet.

| Parameter | Type | Required | Description | | ------------ | ------ | -------- | ------------------------------------------ | | query | string | No | Text to search in memo content | | tag | string | No | Filter by tag (without #) | | visibility | string | No | Filter by visibility | | state | string | No | NORMAL or ARCHIVED (default: NORMAL) | | pageSize | number | No | Results per page (default: 20) | | orderBy | string | No | Sort order (default: display_time desc) |

get_memo

Get a single memo by ID.

| Parameter | Type | Required | Description | | --------- | ------ | -------- | ----------- | | memoId | string | Yes | The memo ID |

update_memo

Update an existing memo.

| Parameter | Type | Required | Description | | ------------ | ------- | -------- | ----------------------------------- | | memo_id | string | Yes | The memo ID to update | | content | string | No | New memo content | | visibility | string | No | PRIVATE, PROTECTED, or PUBLIC | | pinned | boolean | No | Pin or unpin the memo | | state | string | No | NORMAL or ARCHIVED |

Development

Setup

bun install

Running Tests

bun test

Type Checking

bun run typecheck

Linting & Formatting

bun run lint
bun run format

Project Structure

src/
├── index.ts              # MCP server entry point
├── memos-client.ts       # Memos API client
└── memos-client.test.ts  # Tests

License

MIT