Memos MCP Server
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Memos MCP Server create a memo with today's tasks"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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: memopaper-mcp
Installation
Clone this repository or download the files
Install dependencies:
npm installBuild the project:
npm run buildSet 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:
Variable | Required | Default | Description |
| No |
| Your Memos instance base URL |
| No | (empty) | Your Memos API access token |
Usage
Running the Server
npm startOr for development with auto-reload:
npm run devMCP Tools
The server provides the following tools:
create_memo
Create a new memo.
Parameters:
content(required): The memo content in Markdown formatvisibility(optional): Visibility level -PRIVATE,PROTECTED, orPUBLIC(default:PRIVATE)state(optional): Memo state -NORMALorARCHIVED(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 paginationstate(optional): Filter by state -NORMALorARCHIVED(default:NORMAL)orderBy(optional): Sort order (default:display_time desc). Supports:pinned,display_time,create_time,update_time,namefilter(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.,123ormemos/123)
update_memo
Update an existing memo.
Parameters:
memoId(required): The memo ID to updatecontent(optional): New content for the memovisibility(optional): New visibility settingstate(optional): New state settingpinned(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.,123ormemos/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 IDattachments(required): List of attachment objects (use camelCase for attachment fields)filename(required): The filenametype(required): MIME type (e.g.,image/png,application/pdf)content(optional): Base64 encoded file contentexternalLink(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 filenametype(required): MIME type (e.g.,image/png,application/pdf)attachment_id(optional): Custom attachment IDexternal_link(optional): External URLmemo(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.,123orattachments/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 paginationfilter(optional): CEL expression for filteringorder_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 updateupdate_mask(required): Comma-separated list of fields to update (e.g.,filename,type,externalLink)filename(optional): New filenametype(optional): New MIME typeexternal_link(optional): New external URLmemo(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 instancememos://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 outputLicense
MIT License
References
Available Tools
12 toolscreate_attachmentB
Create a new attachment (can be linked to memos later)
Inputs: type (required), filename (required), memo, content, +1 more.
create_memoB
Create a new memo
Inputs: content (required), state, pinned, visibility.
delete_attachmentA
Delete an attachment by ID
Inputs: attachment_id (required).
delete_memoC
Delete a memo
Inputs: memoId (required).
get_attachmentB
Get a specific attachment by ID
Inputs: attachment_id (required).
get_memoB
Get a specific memo by ID
Inputs: memoId (required).
list_attachmentsA
List all attachments with pagination, filtering, and sorting
Inputs: filter, order_by, page_size, page_token.
list_memo_attachmentsA
List all attachments for a specific memo
Inputs: memoId (required), pageSize, pageToken.
list_memosA
List memos with pagination, sorting, and CEL filter support
Inputs: state, filter, orderBy, pageSize, +2 more.
set_memo_attachmentsB
Set attachments for a memo (replaces all existing attachments)
Inputs: memoId (required), attachments (required).
update_attachmentC
Update an existing attachment
Inputs: update_mask (required), attachment_id (required), memo, type, +2 more.
update_memoC
Update an existing memo
Inputs: memoId (required), state, pinned, content, +1 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 12 tools
Each tool clearly targets a distinct resource and action: memo CRUD, attachment CRUD, and attachment-memo relationship operations are separated. list_memo_attachments and list_attachments are distinguished by scope, and set_memo_attachments is clearly different from create_attachment because one associates existing attachments while the other creates them.
All tools follow a consistent snake_case verb_noun pattern: create_, list_, get_, update_, delete_ with the resource clearly named. The relationship tools set_memo_attachments and list_memo_attachments also align with this convention.
12 tools is well-scoped for a server managing two related resources with full CRUD plus relationship operations. Each tool earns its place, and the count is neither bloated nor too thin.
Both memos and attachments have complete lifecycle coverage: create, read, list, update, delete. The additional memo-attachment relationship tools provide the missing linking capability, and set_memo_attachments allows replacement or clearing of attachments, covering all obvious workflows.
Maintenance
Related MCP Connectors
MCP server for interacting with the Supabase platform
The official MCP Server for the Mux API
An MCP server that used to create notes
Related MCP Servers
- AlicenseNot gradedqualityFmaintenanceEnables creating memos and attaching files to a Memos instance via MCP tools.MIT
- AlicenseAqualityDmaintenanceMCP server for memopaper.dev that gives AI agents direct access to a memo buffer, enabling memo creation, retrieval, editing, and deletion via natural language.112 npmMIT
- AlicenseNot gradedqualityDmaintenanceMCP server wrapping a self-hosted mem0 REST API, enabling memory management with deduplication and mention-aware reranked search.MIT
- AlicenseNot gradedqualityCmaintenanceMCP server for Memoo knowledge graph RAG, enabling search, Q&A, graph traversal, and episode management via the Memoo REST API.13 npmApache 2.0