# Memos MCP

Feature-complete [MCP](https://modelcontextprotocol.io/) server for self-hosted [Memos](https://github.com/usememos/memos), with optional **OAuth 2.1 (PKCE)** for remote clients (Cursor / Claude custom connectors).

Inspired by [Red5d/memos_mcp](https://github.com/Red5d/memos_mcp) and [jtsang4/memos-mcp](https://github.com/jtsang4/memos-mcp).

> **OAuth accounts are local to this gateway** (configured via env). They do **not** sync with Memos users. Memos API access always uses `MEMOS_ACCESS_TOKEN`.

## Features

| Area | Tools |
|------|--------|
| Memo CRUD | `memos_search` `memos_get` `memos_create` `memos_update` `memos_delete` |
| Attachments | `memos_list_attachments` `memos_set_attachments` `attachments_list` `attachments_get` `attachments_create` `attachments_delete` |
| Relations / comments | `memos_list_relations` `memos_set_relations` `memos_list_comments` `memos_create_comment` |
| Reactions | `memos_list_reactions` `memos_upsert_reaction` `memos_delete_reaction` |
| Shares | `memos_create_share` `memos_list_shares` `memos_delete_share` `memos_get_shared` |
| Meta | `memos_link_metadata` `memos_whoami` `memos_list_users` `memos_get_user` `memos_user_stats` `memos_instance_profile` `memos_instance_stats` |

## Requirements

- Node.js 20+
- A running Memos instance and an Access Token (Settings → Access Tokens)

## Quick start

```bash
git clone https://github.com/YOUR_USER/memos-mcp.git
cd memos-mcp
cp .env.example .env
# edit .env — at least MEMOS_BASE_URL + MEMOS_ACCESS_TOKEN
npm install
```

### Local stdio (Cursor / Claude Desktop)

No OAuth needed; the process uses `MEMOS_ACCESS_TOKEN` from env.

```json
{
  "mcpServers": {
    "memos": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/memos-mcp/src/index.ts"],
      "env": {
        "MEMOS_BASE_URL": "http://localhost:5230",
        "MEMOS_ACCESS_TOKEN": "your-token"
      }
    }
  }
}
```

### HTTP + OAuth (remote MCP)

```bash
npm run start:http
```

Default: `http://127.0.0.1:3781/mcp`

Set `PUBLIC_URL` to the URL clients will open (e.g. `https://memos-mcp.example.com`). Put nginx/Caddy in front for TLS.

In Cursor, add a remote MCP URL pointing at `/mcp`, then sign in with `OAUTH_USERNAME` / `OAUTH_PASSWORD` from `.env`.

Optional: set `MCP_API_KEY` and call `Authorization: Bearer <key>` to skip the browser OAuth flow (scripts / automation).

## Environment

| Variable | Description |
|----------|-------------|
| `MEMOS_BASE_URL` | Memos base URL |
| `MEMOS_ACCESS_TOKEN` | Memos access token (`MEMOS_API_TOKEN` alias) |
| `OAUTH_USERNAME` / `OAUTH_PASSWORD` | Local OAuth login (HTTP mode) |
| `OAUTH_USERS` | Multi-user JSON: `[{"username":"a","password":"b"}]` |
| `PUBLIC_URL` | Public origin for OAuth metadata |
| `PORT` / `HOST` | Listen address (default `3781` / `0.0.0.0`) |
| `COOKIE_SECURE` | `1` behind HTTPS |
| `MCP_API_KEY` | Optional static Bearer |
| `DATA_DIR` | OAuth state dir (default `./data`, file `oauth.json`) |

## OAuth endpoints

Compatible with MCP OAuth 2.1 clients:

- `GET /.well-known/oauth-authorization-server`
- `GET /.well-known/oauth-protected-resource`
- `GET/POST /oauth/authorize`
- `POST /oauth/token`
- `POST /oauth/register`
- `GET /health` · `POST /mcp`

## Architecture

```
AI Client ──OAuth / API key──► memos-mcp (/mcp)
                                  │
                                  │ Bearer MEMOS_ACCESS_TOKEN
                                  ▼
                               Memos (/api/v1/…)
```

## Development

```bash
npm run typecheck
npm test
npm run dev:http
```

## Security notes for operators

- Never commit `.env` or `data/oauth.json`.
- Prefer strong `OAUTH_PASSWORD` / `MCP_API_KEY` when exposing HTTP publicly.
- Rotate Memos access tokens if they leak.

## License

MIT