MCP Memos Server

A Model Context Protocol (MCP) server that provides AI agents with access to your Memos instance. This server allows AI models to read, write, search, and organize your memos through a standardized interface.

Features

🔧 Tools (Actions)

• set_api_key - 🔑 Set your Memos API key (required first step)

• create_memo - Create new memos with content, tags, and visibility settings

• get_memo - Retrieve specific memos by ID

• update_memo - Modify existing memo content and settings

• delete_memo - Remove memos from your instance

• search_memos - Search through memo content with text queries

• get_memos_by_date - Find memos created on specific dates

• get_memos_by_date_range - Get memos within date ranges

• list_recent_memos - Access your most recent memos

📚 Resources (Data Access)

• memo://recent - Access recent memos

• memo://search/{query} - Search results for specific queries

• memo://date/{YYYY-MM-DD} - Memos from specific dates

• memo://memo/{memo_id} - Individual memo content

Prerequisites

• A running Memos server (self-hosted or cloud)

• A Memos API key (generated in Settings → Access Tokens) - provided by users at runtime

• Docker (optional, but recommended)

• Python 3.11+ (if running without Docker)

Quick Start with Docker

1. Clone or create the project directory:

   git clone <repository> mcp-memos-server cd mcp-memos-server

2. Create environment file:

   cp .env.example .env

3. Edit

   # Required settings MEMOS_URL=https://your-memos-server.com # MEMOS_API_KEY is now optional - users provide it at runtime # Optional settings DEFAULT_VISIBILITY=PRIVATE MAX_SEARCH_RESULTS=50 TIMEOUT=30

4. Run with Docker Compose:

   docker-compose up -d

5. Test the connection:

   docker-compose logs mcp-memos-server

Installation without Docker

1. Install Python dependencies:

   pip install -r requirements.txt

2. Set environment variables:

   export MEMOS_URL="https://your-memos-server.com" # MEMOS_API_KEY is optional - users will provide it at runtime

3. Run the server:

   python server.py

Configuration

Required Environment Variables

Optional Environment Variables (for backwards compatibility)

Optional Environment Variables

Getting Your Memos API Key

1. Open your Memos web interface

2. Go to Settings → Access Tokens

3. Create a new access token

4. Copy the generated token (starts with memos_)

Using with Claude Desktop

Add this to your Claude Desktop MCP configuration:

Or if running locally:

Usage Instructions

🔑 Setting Your API Key (Required First Step)

Before using any memo operations, you must provide your Memos API key using the set_api_key tool:

Important Security Notes:

• Your API key is only stored in memory for the current session

• The key is never logged or persisted to disk

• Each time you restart the MCP server, you'll need to set the API key again

• This is much safer than hardcoding the key in configuration files

Getting Your API Key

1. Open your Memos web interface

2. Go to Settings → Access Tokens

3. Create a new access token

4. Copy the generated token (starts with memos_)

5. Use it with the set_api_key tool

Usage Examples

Creating Memos

Searching Memos

Finding Memos by Date

Accessing Resources

API Documentation

Tools

set_api_key 🔑

Sets your Memos API key for the current session. This must be called first before using any other memo operations.

Parameters:

• api_key (string, required): Your Memos API key from Settings → Access Tokens

Returns: Success/failure message with connection verification

Security: The API key is stored only in memory and never persisted to disk.

create_memo

Creates a new memo in your Memos instance.

Parameters:

• content (string, required): Memo content (Markdown supported)

• visibility (string, optional): PRIVATE, PROTECTED, or PUBLIC

• tags (array, optional): List of tags to add

Returns: Success message with memo ID

search_memos

Searches through your memos by content.

Parameters:

• query (string, required): Search query

• limit (integer, optional): Max results (default: 20)

Returns: List of matching memos

get_memos_by_date

Gets memos created on a specific date.

Parameters:

• date_str (string, required): Date in YYYY-MM-DD format

• limit (integer, optional): Max results (default: 20)

Returns: List of memos from that date

Resources

Resources provide read-only access to your memo data:

• memo://recent - Recent memos

• memo://search/{query} - Search results

• memo://date/{YYYY-MM-DD} - Memos by date

• memo://memo/{memo_id} - Specific memo

Troubleshooting

Connection Issues

• Verify MEMOS_URL is correct (no trailing slash)

• Check that your API key is valid and has proper permissions

• Ensure your Memos server is accessible from the MCP server

Docker Issues

• Check logs: docker-compose logs mcp-memos-server

• Verify environment variables: docker-compose config

• Restart containers: docker-compose restart

Permission Errors

• Ensure your API key has read/write permissions

• Check that your user account has access to the memos you're trying to access

Development

Running Tests

Debugging

Enable debug logging by setting the environment variable:

Contributing

1. Fork the repository

2. Create a feature branch

3. Make your changes

4. Add tests

5. Submit a pull request

License

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

Security Notes

• ✅ Enhanced Security: API keys are no longer stored in configuration files

• 🔑 Runtime API Key: Users provide API keys dynamically via the set_api_key tool

• 📝 Memory Only: API keys are stored only in memory and never persisted to disk

• 🔄 Session-Based: API key must be set again each time the MCP server restarts

• 🐳 Container Security: The Docker container runs as a non-root user

• 🔒 HTTPS: All communication with Memos uses HTTPS (if your server supports it)

• ❌ Never Commit Secrets: Never commit API keys to version control

Support

For issues and feature requests:

1. Check the troubleshooting section

2. Look for existing issues in the repository

3. Create a new issue with detailed information about your setup and the problem