Skip to main content
Glama
yixiaozi

Memos MCP

by yixiaozi
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

Memos MCP

Feature-complete MCP server for self-hosted Memos, with optional OAuth 2.1 (PKCE) for remote clients (Cursor / Claude custom connectors).

Inspired by Red5d/memos_mcp and 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

Related MCP server: Memos MCP Server

Requirements

  • Node.js 20+

  • A running Memos instance and an Access Token (Settings → Access Tokens)

Quick start

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.

{
  "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)

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

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

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • Memos MCP Server

    ShaoRou459
    A
    license
    Not graded
    quality
    D
    maintenance
    Enables AI agents to interact with Memos instances for personal note-taking and knowledge management. Supports creating, searching, updating, and organizing memos with tags, dates, and visibility settings through natural language.
    MIT

  • memos-mcp

    yuzhi-jiang
    A
    license
    A
    quality
    D
    maintenance
    Connects to Memos note-taking service to read, write, search, filter, and manage memos, including creating comments and managing users.
    8
    1
    MIT