memos-fastmcp 0.2.2

MCP server for Memos built with FastMCP - self-hosted note-taking tool

Memos MCP Server

English | 中文

MCP server for Memos - the open-source, self-hosted note-taking tool. Built with FastMCP.

Features

Tools

Memo CRUD:

• create_memo - Create a new memo with content, visibility, and tags
• get_memo - Get a memo by ID
• update_memo - Update memo content, visibility, or pinned status
• delete_memo - Delete a memo
• list_memos - List memos with filters (state, custom filter)
• search_memos - Search memos by content or tags

Tag Management:

• list_tags - List all tags with usage counts
• rename_tag - Rename a tag across all memos
• delete_tag - Delete a tag from all memos

Visibility Control:

• set_visibility - Set memo visibility (PRIVATE, PROTECTED, PUBLIC)
• list_public_memos - List all public memos
• list_private_memos - List all private memos

Resources

• memos://list - Recent 20 memos summary (ID, title, tags, time, visibility)
• memos://{memo_id} - Full details of a specific memo
• memos://tags - All tags with usage counts
• memos://stats - Statistics (total memos, by visibility/state, tags count, pinned)

Prompts

• search_by_tag - Quick search for memos with a specific tag
• create_quick_note - Create a simple memo with optional tag
• find_recent_notes - Find memos from past N days
• organize_by_visibility - Review and organize memos by visibility
• update_memo_prompt - Update a specific memo's content with verification

Installation

# Using pip
pip install memos-fastmcp

# Using uvx (recommended)
uvx memos-fastmcp

Configuration

Get API Token

1. Open your Memos instance
2. Go to Settings > API Keys
3. Generate a new API token

Environment Variables

MEMOS_URL=http://your-memos-instance:5230
MEMOS_TOKEN=your-api-token

Optional:

MEMOS_API_VERSION=v1          # Default: v1
MEMOS_REQUEST_TIMEOUT=30.0    # Default: 30.0 seconds
DISPLAY_STYLE=list            # Default: list (options: list, table)

Output Format

Query tools (list_memos, search_memos, get_memo, list_public_memos, list_private_memos) return Markdown format with two display styles:

Style	Description
list	Detailed list items with full timestamps and status indicators (default)
table	Compact table format for quick scanning

Example list style:

## 📝 V2xmw6RkAEDo4TimKhCGNL

🔗 [查看详情](http://localhost:5230/memos/V2xmw6RkAEDo4TimKhCGNL)

**创建时间:** 2026-04-12 14:30:25
**状态:** 置顶 | 公开
**标签:** #work #project

项目计划已完成初步设计...

Example table style:

| ID | 创建时间 | 状态 | 标签 | 内容 |
|----|----------|------|------|------|
| V2xmw6RkAEDo4TimKhCGNL | 2026-04-12 | 置顶 \| 公开 | #work #project | 项目计划已完成... |

Notes:

• ID column is not truncated (easy to copy for subsequent operations)
• Content truncated: 200 chars in list style, 50 chars in table style
• Hyperlinks point to browser-accessible memo detail pages

Usage with MCP Clients

Claude Desktop / Claude Code

Add to your MCP configuration:

{
  "mcpServers": {
    "memos": {
      "command": "uvx",
      "args": ["memos-fastmcp"],
      "env": {
        "MEMOS_URL": "http://your-memos-instance:5230",
        "MEMOS_TOKEN": "your-api-token"
      }
    }
  }
}

For Claude Desktop, place this in:

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

For Claude Code, place this in .claude/settings.json in your project.

Other MCP Clients

# Run directly with environment variables
MEMOS_URL=http://your-memos-instance:5230 \
MEMOS_TOKEN=your-api-token \
uvx memos-fastmcp

Example Usage

Once configured, you can interact with Memos through Claude:

User: "Create a memo about my project plan with tag 'work'"
Claude: [Uses create_memo tool] "Created memo with ID: abc123..."

User: "Search for all memos tagged 'work'"
Claude: [Uses search_memos tool] "Found 5 memos tagged 'work'..."

User: "What are my most used tags?"
Claude: [Uses memos://tags resource] "Your top tags are: work (12), ideas (8)..."

User: "Show me recent memos from the past week"
Claude: [Uses find_recent_notes prompt] "Here are 7 memos from the past week..."

User: "Pin memo abc123"
Claude: [Uses update_memo tool] "Successfully pinned memo abc123"

Development

Local Setup

git clone https://github.com/Jiraiya8/memos-mcp.git
cd memos-mcp

# Install dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run locally
MEMOS_URL=http://localhost:5230 MEMOS_TOKEN=your-token python -m memos_mcp.server

Build & Publish

python -m build
twine upload dist/*

API Compatibility

Compatible with Memos API v1. Requires Memos 0.22.0 or later.

License

MIT License - see LICENSE for details.

Links

• PyPI
• GitHub
• Memos
• FastMCP