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.

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.