MCP Integration

YoMemo provides an out-of-the-box MCP server that can be used as an encrypted memory backend for clients supporting the Model Context Protocol (MCP), such as Claude, Cursor, and other IDEs. You can mount YoMemo as a “secure memory layer” in your LLM tools, similar to how you would mount a file system or database.

Prerequisites

Before you begin, you need:

• A deployed or locally running YoMemo API service
• A valid API Key
• An RSA key pair with the private key file stored locally (the server only stores the public key)
• uv or Python environment installed

For MCP clients, you can choose from: Claude Desktop, Cursor, Zed, or any other tool that supports MCP.

Installation

The recommended way is to use uvx to run directly without explicit installation:

uvx yomemoai-mcp --help

If you prefer to install via pip (optional):

pip install yomemoai-mcp

Configure MCP Client

For typical MCP clients (such as Claude / Cursor), you only need to add a mcpServers configuration section to their configuration file.

Here’s an example configuration. Replace MEMO_API_KEY and the private key path with your own values:

{
  "mcpServers": {
    "yomemoai-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "yomemoai-mcp"
      ],
      "env": {
        "MEMO_API_KEY": "your_api_key_here",
        "MEMO_PRIVATE_KEY_PATH": "/path/to/private.pem"
      }
    }
  }
}

Configuration Options

• type: "stdio"
  The MCP client communicates with yomemoai-mcp process through standard input/output.

• command: "uvx" and args: ["yomemoai-mcp"]
  Uses uvx to launch and run yomemoai-mcp, so you don’t need to install the executable separately in your global environment.

• MEMO_API_KEY
  Your YoMemo backend API Key for authentication. Treat this as a secret and only store it in local configuration or secure key management tools.

• MEMO_PRIVATE_KEY_PATH
  Path to your local RSA private key PEM file.
  The private key is only stored locally and is used for decryption and signing. The YoMemo server only stores the public key and cannot decrypt your memory content.

Caution

Never commit MEMO_API_KEY or private key files to Git repositories.
It’s recommended to manage them through environment variables or local configuration files that are not version controlled.

Using with Claude / Cursor

Claude Desktop

1. Open Claude Desktop’s MCP configuration file (usually a JSON/JSONC file).
2. Add the mcpServers.yomemoai-mcp section from above.
3. Restart the Claude client or trigger a configuration refresh.
4. In conversations, you can have Claude use yomemoai-mcp tools to:
   • Write new encrypted memories (such as user preferences, long conversation summaries)
   • Retrieve historical memories from YoMemo and use them for context enhancement

Cursor

1. Add a new MCP server in Cursor’s MCP/tool configuration panel.
2. Fill in the same command / args / env values.
3. After restarting Cursor, you’ll see YoMemo-related MCP tools in the command palette and can invoke them in Codebase / Chat.

How It Works

In relation to YoMemo’s architecture (see docs/llm.md), the MCP integration works as follows:

• MCP clients (Claude / Cursor, etc.) call yomemoai-mcp
• yomemoai-mcp acts as a “bridge layer”, converting these calls into HTTP requests to the YoMemo API:
  • On write: Uses your local private key to encrypt and sign content, then saves it to the backend via YoMemo API
  • On read: Fetches encrypted data from YoMemo, decrypts it locally with the private key, then returns it to the MCP client
• Throughout the entire process, the YoMemo server only handles encrypted ciphertext and public keys, and cannot see plaintext

In simplified terms, MCP is just an additional “frontend tool” layer, but key management and security model still fully follow YoMemo’s original end-to-end encryption design.

Debugging and Troubleshooting

If you encounter issues during integration, you can:

• Run locally directly:

  MEMO_API_KEY="your_api_key_here" \
  MEMO_PRIVATE_KEY_PATH="/path/to/private.pem" \
  uvx yomemoai-mcp

• Check yomemoai-mcp log output to confirm:

  • Whether the API Key is valid
  • Whether it can connect to the YoMemo API service normally
  • Whether the private key path is correct and the file is readable

Note

MCP is just a new “entry point” and does not change YoMemo’s encryption or data model.
If you’re already familiar with the Go SDK / HTTP API, MCP is just a different way to call YoMemo from IDEs / Chat.

Next Steps

• Read Getting Started to learn the basics of the Go SDK
• Explore How It Works to understand the encryption flow in depth
• Return to the YoMemo Docs overview