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 .env with your Memos configuration:

   # 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

Variable	Description	Example
MEMOS_URL	Base URL of your Memos server	https://memos.example.com

Optional Environment Variables (for backwards compatibility)

Variable	Description	Example
MEMOS_API_KEY	API key from Memos Settings → Access Tokens (optional - users can provide at runtime)	memos_xxx...

Optional Environment Variables

Variable	Default	Description
DEFAULT_VISIBILITY	PRIVATE	Default visibility for new memos (PRIVATE, PROTECTED, PUBLIC)
MAX_SEARCH_RESULTS	50	Maximum number of search results to return
TIMEOUT	30	HTTP request timeout in seconds

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:

{
  "mcpServers": {
    "memos": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "--env-file", "/path/to/your/.env",
        "mcp-memos-server"
      ]
    }
  }
}

Or if running locally:

{
  "mcpServers": {
    "memos": {
      "command": "python",
      "args": ["/path/to/mcp-memos-server/server.py"],
      "env": {
        "MEMOS_URL": "https://your-memos-server.com"
        // API key no longer needed here - users provide it at runtime
      }
    }
  }
}

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:

AI: I need to set up access to your Memos server first. Please use the set_api_key tool.
User: set_api_key
Tool Parameters: {
  "api_key": "memos_your_actual_api_key_here"
}
Response: ✅ API key set successfully and connection verified

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

AI: I'll create a memo about today's meeting notes.
Tool: create_memo
Args: {
  "content": "# Team Meeting - 2024-01-15\n\n- Discussed Q1 goals\n- Assigned tasks for sprint\n- Next meeting: Jan 22",
  "visibility": "PRIVATE",
  "tags": ["meeting", "team", "Q1"]
}

Searching Memos

AI: Let me search for memos about "project planning"
Tool: search_memos
Args: {
  "query": "project planning",
  "limit": 10
}

Finding Memos by Date

AI: Show me all memos from yesterday
Tool: get_memos_by_date
Args: {
  "date_str": "2024-01-14",
  "limit": 20
}

Accessing Resources

AI: Let me check your recent memos
Resource: memo://recent

AI: I'll search for memos about "vacation"
Resource: memo://search/vacation

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

python test_server.py

Debugging

Enable debug logging by setting the environment variable:

export MCP_LOG_LEVEL=DEBUG

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