# Memento MCP Server

Model Context Protocol (MCP) server for integrating Memento note-taking app with N8N, Claude Desktop, and other MCP clients.

## Quick Start

```bash
cd mcp-server
npm install
```

### stdio Mode (Claude Desktop, Cline)

```bash
node index.js
```

Claude Desktop configuration:
```json
{
  "mcpServers": {
    "memento": {
      "command": "docker",
      "args": ["exec", "-i", "memento-mcp", "node", "index.js"]
    }
  }
}
```

### HTTP Streamable Mode (N8N, remote)

```bash
node index-sse.js
```

Requires `DATABASE_URL` environment variable pointing to your PostgreSQL database.

For Docker deployment, MCP_MODE and MCP_REQUIRE_AUTH are pre-configured in `docker-compose.yml`.

## Authentication

When `MCP_REQUIRE_AUTH=true` (default in Docker), all requests require an `x-api-key` header.

Generate API keys from the Memento web UI: **Settings > MCP**.

```bash
# Example: health check with API key
curl -H "x-api-key: mcp_sk_xxx" http://localhost:3001/
```

## Available Tools (25)

### Notes (11)

| Tool | Description |
|------|-------------|
| `create_note` | Create a new note |
| `get_notes` | List notes (filterable) |
| `get_note` | Get a specific note by ID |
| `update_note` | Update an existing note |
| `delete_note` | Delete a note |
| `search_notes` | Search notes by keyword |
| `move_note` | Move a note to a notebook |
| `toggle_pin` | Pin/unpin a note |
| `toggle_archive` | Archive/unarchive a note |
| `export_notes` | Export notes as JSON |
| `import_notes` | Import notes from JSON |
| `batch_move_notes` | Move multiple notes at once |
| `batch_delete_notes` | Delete multiple notes at once |

### Notebooks (6)

| Tool | Description |
|------|-------------|
| `create_notebook` | Create a notebook |
| `get_notebooks` | List all notebooks |
| `get_notebook` | Get notebook details |
| `update_notebook` | Update a notebook |
| `delete_notebook` | Delete a notebook |
| `reorder_notebooks` | Reorder notebooks |
| `get_notebook_hierarchy` | Get tree structure of notebooks |

### Labels (4)

| Tool | Description |
|------|-------------|
| `create_label` | Create a label |
| `get_labels` | List labels |
| `update_label` | Update a label |
| `delete_label` | Delete a label |

### Reminders (1)

| Tool | Description |
|------|-------------|
| `get_due_reminders` | Get due reminders |

## N8N Integration

### MCP Client Node Configuration

1. Add a **MCP Client** node in N8N
2. Select **Streamable HTTP** as transport
3. Endpoint: `http://memento-mcp:3001/mcp` (Docker) or `http://YOUR_IP:3001/mcp`
4. Add **Header Auth**: `x-api-key` = your MCP API key

### Example Workflow: Create a note from email

```json
{
  "tool": "create_note",
  "arguments": {
    "title": "{{ $json.subject }}",
    "content": "{{ $json.body }}",
    "labels": ["email", "inbox"]
  }
}
```

## HTTP Endpoints

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/` | GET | Health check |
| `/mcp` | GET/POST | Main MCP endpoint (Streamable HTTP) |
| `/sse` | GET/POST | Legacy redirect to `/mcp` |
| `/sessions` | GET | Active sessions |

## Configuration

| Variable | Default | Description |
|----------|---------|-------------|
| `PORT` | 3001 | Server port |
| `DATABASE_URL` | required | PostgreSQL connection string |
| `MCP_MODE` | stdio | Transport mode (stdio or sse) |
| `MCP_REQUIRE_AUTH` | false | Require x-api-key header |
| `MCP_LOG_LEVEL` | info | Log level (debug, info, warn, error) |
| `MCP_REQUEST_TIMEOUT` | 30000 | Request timeout in ms |
| `APP_BASE_URL` | http://localhost:3000 | Memento app URL |

## License

MIT