Memos MCP Server
An MCP (Model Context Protocol) server that provides tools for interacting with a Memos instance. This server allows AI assistants to search, create, and update memos through the Memos API.
Features
- Search Memos: Search for memos with filters like creator, tags, visibility, and content
- Create Memos: Create new memos with markdown support
- Update Memos: Update existing memos (content, visibility, pinned status)
- Get Memo: Retrieve a specific memo by UID
Installation
- Clone this repository:```bash
git clone <repository-url>
cd memos_mcp
2. Install dependencies:
### Using uv (recommended)```bash
uv sync
Using pip```bash
pip install -r requirements.txt
## Configuration
Set the following environment variables:
- `MEMOS_BASE_URL`: The base URL of your Memos instance (default: `http://localhost:5230`)
- `MEMOS_API_TOKEN`: Your Memos API authentication token (optional for public instances)
### Getting an API Token
1. Log into your Memos instance
2. Go to Settings → Access Tokens
3. Create a new access token
4. Copy the token and set it as the `MEMOS_API_TOKEN` environment variable
Example:```bash
export MEMOS_BASE_URL="https://memos.example.com"
export MEMOS_API_TOKEN="your-token-here"
Usage
Running the Server
Using uvx (no installation required)```bash
Run directly with uvx
uvx --from . memos-mcp
#### Using uv after installation```bash
# After running 'uv sync'
uv run memos-mcp
Using FastMCP directly```bash
fastmcp run server.py
#### Programmatic usage```python
from server import mcp
# The server is ready to use
Available Tools
1. search_memos
Search for memos with optional filters.
Parameters:
- query (optional): Text to search for in memo content
- creator_id (optional): Filter by creator user ID
- tag (optional): Filter by tag name
- visibility (optional): Filter by visibility (PUBLIC, PROTECTED, PRIVATE)
- limit (default: 10): Maximum number of results
- offset (default: 0): Number of results to skip
Example:```python
result = await search_memos(query="meeting notes", limit=5)
#### 2. create_memo
Create a new memo.
**Parameters:**
- `content`: The content of the memo (supports Markdown)
- `visibility` (default: PRIVATE): Visibility level (PUBLIC, PROTECTED, PRIVATE)
**Example:**```python
result = await create_memo(
content="# Meeting Notes\n\n- Discuss project timeline\n- Review budget",
visibility="PRIVATE"
)
3. update_memo
Update an existing memo.
Parameters:
- memo_uid: The UID of the memo to update
- content (optional): New content for the memo
- visibility (optional): New visibility level
- pinned (optional): Whether to pin the memo
Example:```python
result = await update_memo(
memo_uid="abc123",
content="Updated content",
pinned=True
)
#### 4. get_memo
Get a specific memo by its UID.
**Parameters:**
- `memo_uid`: The UID of the memo to retrieve
**Example:**```python
result = await get_memo(memo_uid="abc123")
Integration with MCP Clients
Claude Desktop
Add to your Claude Desktop configuration file:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Using uvx (recommended - no installation needed)```json
{
"mcpServers": {
"memos": {
"command": "uvx",
"args": ["--from", "/path/to/memos_mcp", "memos-mcp"],
"env": {
"MEMOS_BASE_URL": "http://localhost:5230",
"MEMOS_API_TOKEN": "your-token-here"
}
}
}
}
#### Using uv (after installation)```json
{
"mcpServers": {
"memos": {
"command": "uv",
"args": ["run", "--directory", "/path/to/memos_mcp", "memos-mcp"],
"env": {
"MEMOS_BASE_URL": "http://localhost:5230",
"MEMOS_API_TOKEN": "your-token-here"
}
}
}
}
Using Python directly```json
{
"mcpServers": {
"memos": {
"command": "python",
"args": ["-m", "fastmcp", "run", "/path/to/memos_mcp/server.py"],
"env": {
"MEMOS_BASE_URL": "http://localhost:5230",
"MEMOS_API_TOKEN": "your-token-here"
}
}
}
}
## API Reference
This server is built on the Memos API v1. The API follows Google's API Improvement Proposals (AIPs) design guidelines.
### API Endpoints Used
- `GET /api/v1/memos` - List/search memos
- `POST /api/v1/memos` - Create a memo
- `GET /api/v1/memos/{uid}` - Get a specific memo
- `PATCH /api/v1/memos/{uid}` - Update a memo
### Authentication
The server supports Bearer token authentication. Include your access token in the `Authorization` header:```
Authorization: Bearer your-token-here
Development
Running Tests```bash
pytest
```
Code Structure
server.py: Main MCP server implementation with all toolsrequirements.txt: Python dependencies
About Memos
Memos is a lightweight, self-hosted memo hub with knowledge management and social networking features. Learn more at:
- Website: https://www.usememos.com/
- GitHub: https://github.com/usememos/memos
License
MIT License - see LICENSE file for details
Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
