Memos MCP Server

A Model Context Protocol (MCP) server for interacting with Memos API.

Features

• Create Memos: Create new memos with Markdown content

• List Memos: List memos with pagination, sorting, and CEL filter support

• Get Memo: Retrieve a specific memo by ID

• Update Memo: Update existing memo content and metadata

• Delete Memo: Delete memos

• Memo Attachments: List and set memo attachments

• Attachment Service: Create, list, get, update, and delete individual attachments

Related MCP server: memos-mcp-server

Installation

1. Clone this repository or download the files

2. Install dependencies:

npm install

3. Build the project:

npm run build

4. Set up environment variables:

export MEMOS_BASE_URL="https://your-memos-instance.com"
export MEMOS_API_KEY="your-api-token"

For Memos API key, go to your Memos instance -> Settings -> API to generate a token.

Configuration

The server uses the following environment variables:

Usage

Running the Server

npm start

Or for development with auto-reload:

npm run dev

MCP Tools

The server provides the following tools:

create_memo

Create a new memo.

Parameters:

• content (required): The memo content in Markdown format

• visibility (optional): Visibility level - PRIVATE, PROTECTED, or PUBLIC (default: PRIVATE)

• state (optional): Memo state - NORMAL or ARCHIVED (default: NORMAL)

• pinned (optional): Whether to pin the memo (default: false)

Example:

{
  "content": "# My First Memo\n\nThis is a **markdown** memo.",
  "visibility": "PRIVATE",
  "pinned": false
}

list_memos

List memos with pagination, sorting, and CEL filter support.

Parameters:

• pageSize (optional): Maximum number of memos to return (default: 50, max: 1000)

• pageToken (optional): Page token from previous response for pagination

• state (optional): Filter by state - NORMAL or ARCHIVED (default: NORMAL)

• orderBy (optional): Sort order (default: display_time desc). Supports: pinned, display_time, create_time, update_time, name

• filter (optional): CEL expression for advanced filtering (e.g., visibility == 'PUBLIC')

• show_deleted (optional): Include deleted memos (default: false)

Examples:

// Basic list
{
  "pageSize": 50,
  "state": "NORMAL"
}

// With CEL filter
{
  "filter": "visibility == 'PUBLIC' && content.contains('meeting')",
  "orderBy": "pinned desc, display_time desc"
}

// Pagination
{
  "pageSize": 50,
  "pageToken": "eyJwYWdlU2l6ZSI6IDUwfQ=="
}

get_memo

Get a specific memo by ID.

Parameters:

• memoId (required): The memo ID (e.g., 123 or memos/123)

update_memo

Update an existing memo.

Parameters:

• memoId (required): The memo ID to update

• content (optional): New content for the memo

• visibility (optional): New visibility setting

• state (optional): New state setting

• pinned (optional): New pinned state

delete_memo

Delete a memo.

Parameters:

• memoId (required): The memo ID to delete

list_memo_attachments

List all attachments for a specific memo.

Parameters:

• memoId (required): The memo ID (e.g., 123 or memos/123)

• pageSize (optional): Maximum number of attachments to return (default: 50, max: 1000)

• pageToken (optional): Page token for pagination

Example:

{
  "memoId": "123",
  "pageSize": 100
}

set_memo_attachments

Set attachments for a memo (replaces all existing attachments).

Parameters:

• memoId (required): The memo ID

• attachments (required): List of attachment objects (use camelCase for attachment fields)

  • filename (required): The filename

  • type (required): MIME type (e.g., image/png, application/pdf)

  • content (optional): Base64 encoded file content

  • externalLink (optional): External URL (camelCase)

Note: Use content OR externalLink, not both. Do NOT include size or createTime (these are server-generated).

Important: Attachment fields must use camelCase (externalLink, not external_link) as they match the API specification.

Example:

{
  "memoId": "123",
  "attachments": [
    {
      "filename": "document.pdf",
      "type": "application/pdf",
      "externalLink": "https://example.com/doc.pdf"
    },
    {
      "filename": "small-image.png",
      "type": "image/png",
      "content": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg=="
    }
  ]
}

create_attachment

Create a new attachment (can be linked to memos later).

Parameters:

• filename (required): The filename

• type (required): MIME type (e.g., image/png, application/pdf)

• attachment_id (optional): Custom attachment ID

• external_link (optional): External URL

• memo (optional): Related memo resource name (format: memos/{memo})

Example:

{
  "filename": "document.pdf",
  "type": "application/pdf",
  "external_link": "https://example.com/doc.pdf",
  "memo": "memos/123"
}

get_attachment

Get a specific attachment by ID.

Parameters:

• attachment_id (required): The attachment ID (e.g., 123 or attachments/123)

list_attachments

List all attachments with pagination, filtering, and sorting.

Parameters:

• page_size (optional): Maximum number of attachments to return (default: 50, max: 1000)

• page_token (optional): Page token for pagination

• filter (optional): CEL expression for filtering

• order_by (optional): Sort order (e.g., create_time desc, filename asc)

Examples:

// Basic list
{
  "page_size": 100
}

// With CEL filter
{
  "filter": "mime_type==\"image/png\"",
  "orderBy": "create_time desc"
}

// Filter by memo
{
  "filter": "memo==\"memos/123\""
}

update_attachment

Update an existing attachment.

Parameters:

• attachment_id (required): The attachment ID to update

• update_mask (required): Comma-separated list of fields to update (e.g., filename,type,externalLink)

• filename (optional): New filename

• type (optional): New MIME type

• external_link (optional): New external URL

• memo (optional): New related memo resource name

Example:

{
  "attachmentId": "123"",
  "update_mask": "filename,externalLink",
  "filename": "updated-name.pdf",
  "external_link": "https://example.com/new-url.pdf"
}

delete_attachment

Delete an attachment by ID.

Parameters:

• attachment_id (required): The attachment ID to delete

MCP Resources

The server provides the following resources:

• memos://memos: All memos from your Memos instance

• memos://config: Current server configuration

Claude Desktop Integration

To use this server with Claude Desktop, add it to your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "memos": {
      "command": "node",
      "args": ["/path/to/memos-mcp/dist/index.js"],
      "env": {
        "MEMOS_BASE_URL": "https://your-memos-instance.com",
        "MEMOS_API_KEY": "your-api-token"
      }
    }
  }
}

Development

Project Structure

memos-mcp/
├── package.json           # Node.js project configuration
├── tsconfig.json          # TypeScript configuration
├── src/
│   ├── index.ts           # Entry point
│   ├── server.ts          # MCP server definition
│   ├── memos-client.ts    # Memos API client
│   ├── types.ts           # TypeScript type definitions
│   └── tools/
│       ├── memo-tools.ts      # Memo-related tools
│       └── attachment-tools.ts # Attachment-related tools
└── dist/                  # Compiled JavaScript output

License

MIT License

References

• Memos API Documentation

• Model Context Protocol