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

Clone this repository:

git clone <repository-url> cd memos_mcp

Install dependencies:

Using uv (recommended)

uv sync

Using pip

pip install -r requirements.txt

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

Log into your Memos instance
Go to Settings → Access Tokens
Create a new access token
Copy the token and set it as the MEMOS_API_TOKEN environment variable

Example:

export MEMOS_BASE_URL="https://memos.example.com" export MEMOS_API_TOKEN="your-token-here"

Usage

Running the Server

Using uvx (no installation required)

# Run directly with uvx uvx --from . memos-mcp

Using uv after installation

# After running 'uv sync' uv run memos-mcp

Using FastMCP directly

fastmcp run server.py

Programmatic usage

from server import mcp # The server is ready to use

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:

result = await search_memos(query="meeting notes", limit=5)

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:

result = await create_memo( content="# Meeting Notes\n\n- Discuss project timeline\n- Review budget", visibility="PRIVATE" )

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:

result = await update_memo( memo_uid="abc123", content="Updated content", pinned=True )

4. get_memo

Get a specific memo by its UID.

Parameters:

memo_uid: The UID of the memo to retrieve

Example:

result = await get_memo(memo_uid="abc123")

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)

{ "mcpServers": { "memos": { "command": "uvx", "args": ["--from", "/path/to/memos_mcp", "memos-mcp"], "env": { "MEMOS_BASE_URL": "http://localhost:5230", "MEMOS_API_TOKEN": "your-token-here" } } } }

Using uv (after installation)

{ "mcpServers": { "memos": { "command": "uv", "args": ["run", "--directory", "/path/to/memos_mcp", "memos-mcp"], "env": { "MEMOS_BASE_URL": "http://localhost:5230", "MEMOS_API_TOKEN": "your-token-here" } } } }

Using Python directly

{ "mcpServers": { "memos": { "command": "python", "args": ["-m", "fastmcp", "run", "/path/to/memos_mcp/server.py"], "env": { "MEMOS_BASE_URL": "http://localhost:5230", "MEMOS_API_TOKEN": "your-token-here" } } } }

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:

Authorization: Bearer your-token-here

Development

Running Tests

pytest

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.

This server cannot be installed

-

security - not tested

A

license - permissive license

-

quality - not tested

How are these scores calculated?

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

Enables AI assistants to interact with Memos instances for knowledge management. Supports searching, creating, updating, and retrieving memos with markdown content, tags, and visibility controls.

Memos MCP Server

Memos MCP Server

Features

Installation

Using uv (recommended)

Using pip

Configuration

Getting an API Token

Usage

Running the Server

Using uvx (no installation required)

Using uv after installation

Using FastMCP directly

Programmatic usage

Available Tools

1. search_memos

2. create_memo

3. update_memo

4. get_memo

Integration with MCP Clients

Claude Desktop

Using uvx (recommended - no installation needed)

Using uv (after installation)

Using Python directly

API Reference

API Endpoints Used

Authentication

Development

Running Tests

Code Structure

About Memos

License

Contributing

New MCP Servers

MCP directory API