# Memos MCP Server

A FastMCP-based MCP (Model Context Protocol) server implementation for [Memos](https://github.com/usememos/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**
   ```bash
   git clone <repository-url>
   cd memos-mcp
   ```

2. **Install dependencies**
   ```bash
   uv sync
   ```

3. **Set environment variables**
   ```bash
   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**
   ```bash
   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)**
   ```bash
   # 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**
   ```bash
   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](https://github.com/astral-sh/uv) is installed
2. Clone the repository and install dependencies:
   ```bash
   uv sync
   ```
3. Set environment variables and run:
   ```bash
   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](https://github.com/jlowin/fastmcp)
- [Memos](https://github.com/usememos/memos)
- [Model Context Protocol](https://modelcontextprotocol.io/)