Memos Server

A FastMCP-based MCP (Model Context Protocol) server implementation for Memos, allowing AI assistants to interact with the Memos note-taking system through the MCP protocol.

Features

• 📝 Create Memos - Create new memos with Markdown support
• 📖 Read Memos - Get detailed information about specific memos
• ✏️ Update Memos - Modify existing memo content and properties
• 🗑️ Delete Memos - Remove specified memos
• 📋 Get Recent Memos - Retrieve a list of recent memos
• 🔐 Authentication - Optional static token verification support
• 🐳 Docker Support - Docker and Docker Compose configurations provided

Environment Variables

Before starting the service, you need to set the following environment variables:

Required Environment Variables

Variable Name	Description	Example
MEMOS_SERVER_URL	URL of the Memos server	https://memos.example.com
MEMOS_API_KEY	Memos API key	your-api-key-here

Optional Environment Variables

Variable Name	Description	Default	Example
MEMOS_MCP_AUTH_TOKEN	MCP server authentication token	None	abcdefghijklmnopqrstuvwxyz

Quick Start

Local Development

1. Clone the repository

   git clone <repository-url>
   cd memos-mcp
   

2. Install dependencies

   uv sync
   

3. Set environment variables

   export MEMOS_SERVER_URL="https://your-memos-server.com"
   export MEMOS_API_KEY="your-api-key"
   # Optional: Set authentication token
   export MEMOS_MCP_AUTH_TOKEN="your-auth-token"
   

4. Start the service

   uv run main.py
   

The service will start at http://localhost:8000 with the MCP endpoint at http://localhost:8000/mcp.

Using Docker

1. Using Docker Compose (Recommended)

   # Set environment variables
   export MEMOS_SERVER_URL="https://your-memos-server.com"
   export MEMOS_API_KEY="your-api-key"
   
   # Start the service
   docker-compose up -d
   

2. Using Docker directly

   docker build -t memos-mcp .
   docker run -p 8000:8000 \
     -e MEMOS_SERVER_URL="https://your-memos-server.com" \
     -e MEMOS_API_KEY="your-api-key" \
     memos-mcp
   

Connection

• Protocol: HTTP
• Endpoint: http://localhost:8000/mcp
• Port: 8000

Available Tools and Resources

Tools

create_memo

Create a new memo

• Parameters:
  • content (string): Memo content with Markdown support
  • visibility (string, optional): Visibility setting, defaults to VISIBILITY_UNSPECIFIED
    • PRIVATE: Private
    • PROTECTED: Protected
    • PUBLIC: Public
    • VISIBILITY_UNSPECIFIED: Unspecified

update_memo

Update an existing memo

• Parameters:
  • memo_resource_name (string): Memo resource name (e.g., memos/123 or 123)
  • content (string, optional): New memo content
  • state (string, optional): Memo state
    • STATE_UNSPECIFIED: Unspecified
    • ACTIVE: Active
    • ARCHIVED: Archived
  • visibility (string, optional): Visibility setting
  • pinned (boolean, optional): Whether the memo is pinned

delete_memo

Delete a memo

• Parameters:
  • memo_resource_name (string): Resource name of the memo to delete

Resources

memos://{memo_resource_name}/info

Get detailed information about a specific memo

• Returns: Information including state, content, visibility, creation time, update time, tags, pinned status, and attachments

memos://recent_memos

Get a list of recent memos

• Returns: A list of recent memos, each containing name, state, content, and visibility

Development

Project Structure

memos-mcp/
├── main.py              # Main service file
├── pyproject.toml       # Project configuration
├── Dockerfile           # Docker configuration
├── docker-compose.yaml  # Docker Compose configuration
└── README.md           # Project documentation

Dependencies

• Python >= 3.13
• fastmcp >= 2.12.2
• requests >= 2.32.5

Development Environment Setup

1. Ensure uv is installed
2. Clone the repository and install dependencies:

   uv sync
   

3. Set environment variables and run:

   uv run main.py
   

License

This project is licensed under the MIT License. See the LICENSE file for details.

Contributing

Issues and Pull Requests are welcome!

Related Links

• FastMCP
• Memos
• Model Context Protocol