Memos MCP Server

An MCP (Model Context Protocol) server that provides tools for interacting with a Memos instance. This server allows AI assistants to search, create, and update memos through the Memos API.

Features

• Search Memos: Search for memos with filters like creator, tags, visibility, and content

• Create Memos: Create new memos with markdown support

• Update Memos: Update existing memos (content, visibility, pinned status)

• Get Memo: Retrieve a specific memo by UID

Installation

1. Clone this repository:

2. Install dependencies:

Using uv (recommended)

Using pip

Configuration

Set the following environment variables:

• MEMOS_BASE_URL: The base URL of your Memos instance (default: http://localhost:5230)

• MEMOS_API_TOKEN: Your Memos API authentication token (optional for public instances)

Getting an API Token

1. Log into your Memos instance

2. Go to Settings → Access Tokens

3. Create a new access token

4. Copy the token and set it as the MEMOS_API_TOKEN environment variable

Example:

Usage

Running the Server

Using uvx (no installation required)

Using uv after installation

Using FastMCP directly

Programmatic usage

Available Tools

1. search_memos

Search for memos with optional filters.

Parameters:

• query (optional): Text to search for in memo content

• creator_id (optional): Filter by creator user ID

• tag (optional): Filter by tag name

• visibility (optional): Filter by visibility (PUBLIC, PROTECTED, PRIVATE)

• limit (default: 10): Maximum number of results

• offset (default: 0): Number of results to skip

Example:

2. create_memo

Create a new memo.

Parameters:

• content: The content of the memo (supports Markdown)

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

Example:

3. update_memo

Update an existing memo.

Parameters:

• memo_uid: The UID of the memo to update

• content (optional): New content for the memo

• visibility (optional): New visibility level

• pinned (optional): Whether to pin the memo

Example:

4. get_memo

Get a specific memo by its UID.

Parameters:

• memo_uid: The UID of the memo to retrieve

Example:

Integration with MCP Clients

Claude Desktop

Add to your Claude Desktop configuration file:

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

Using uvx (recommended - no installation needed)

Using uv (after installation)

Using Python directly

API Reference

This server is built on the Memos API v1. The API follows Google's API Improvement Proposals (AIPs) design guidelines.

API Endpoints Used

• GET /api/v1/memos - List/search memos

• POST /api/v1/memos - Create a memo

• GET /api/v1/memos/{uid} - Get a specific memo

• PATCH /api/v1/memos/{uid} - Update a memo

Authentication

The server supports Bearer token authentication. Include your access token in the Authorization header:

Development

Running Tests

Code Structure

• server.py: Main MCP server implementation with all tools

• requirements.txt: Python dependencies

About Memos

Memos is a lightweight, self-hosted memo hub with knowledge management and social networking features. Learn more at:

• Website: https://www.usememos.com/

• GitHub: https://github.com/usememos/memos

License

MIT License - see LICENSE file for details

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.