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 memosmemo://search/{query}- Search results for specific queriesmemo://date/{YYYY-MM-DD}- Memos from specific datesmemo://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
-
Clone or create the project directory:
git clone <repository> mcp-memos-server cd mcp-memos-server -
Create environment file:
cp .env.example .env -
Edit
.envwith 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 -
Run with Docker Compose:
docker-compose up -d -
Test the connection:
docker-compose logs mcp-memos-server
Installation without Docker
-
Install Python dependencies:
pip install -r requirements.txt -
Set environment variables:
export MEMOS_URL="https://your-memos-server.com" # MEMOS_API_KEY is optional - users will provide it at runtime -
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
- Open your Memos web interface
- Go to Settings → Access Tokens
- Create a new access token
- 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
- Open your Memos web interface
- Go to Settings → Access Tokens
- Create a new access token
- Copy the generated token (starts with
memos_) - Use it with the
set_api_keytool
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, orPUBLICtags(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 querylimit(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 inYYYY-MM-DDformatlimit(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 memosmemo://search/{query}- Search resultsmemo://date/{YYYY-MM-DD}- Memos by datememo://memo/{memo_id}- Specific memo
Troubleshooting
Connection Issues
- Verify
MEMOS_URLis 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
- Fork the repository
- Create a feature branch
- Make your changes
- Add tests
- 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_keytool - 📝 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:
- Check the troubleshooting section
- Look for existing issues in the repository
- Create a new issue with detailed information about your setup and the problem