This MCP server provides an interface to interact with a Memos note-taking backend using the Model Context Protocol. It exposes tools to create, read, update, delete, and list memos, with optional authentication support. You can query for memo details, fetch recent memos, and manage memo content with Markdown support. The server communicates over HTTP at the MCP endpoint and is designed to integrate with AI assistants and plugins that speak MCP-compatible commands.

Key capabilities include: create_memo to add new memos with Markdown content, update_memo to modify content, state, visibility, or pin status, delete_memo to remove a memo, and info at memos://{memo_resource_name}/info to fetch detailed memo metadata. You can also retrieve recent memos via memos://recent_memos. The protocol and endpoints are designed to be consumed by clients that understand FastMCP-style commands and responses.

Prerequisites:

• Python 3.13 or newer
• uv (FastMCP/uv-based tooling) installed
• Access to a running Memos server (MEMOS_SERVER_URL) and an API key (MEMOS_API_KEY)

Install and run locally:

1. Clone the repository: git clone <repository-url> cd memos-mcp

2. Install dependencies and start the server with uv: uv sync uv run main.py

3. Configure environment variables (example): export MEMOS_SERVER_URL="https://your-memos-server.com" export MEMOS_API_KEY="your-api-key"

   Optional: authentication for MCP clients

   export MEMOS_MCP_AUTH_TOKEN="your-auth-token"

4. Verify the service starts and the MCP endpoint is available at: http://localhost:8000/mcp

Docker (optional):

• Docker Compose:
  • Set MEMOS_SERVER_URL and MEMOS_API_KEY in a .env file or your environment
  • docker-compose up -d
• Docker run: 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

Tips and common considerations:

• Ensure MEMOS_SERVER_URL and MEMOS_API_KEY are correctly set; the MCP server will reuse these to talk to the Memos backend.
• If you enable MCP authentication, provide MEMOS_MCP_AUTH_TOKEN to restrict access.
• The MCP endpoint is typically exposed at http://localhost:8000/mcp with HTTP protocol; adjust firewall and port mappings as needed in your environment.
• If you encounter network or authentication issues, verify that the Memos API is reachable from the MCP server and that the API key is valid.
• When using Docker, remember to expose port 8000 if you want to access the MCP endpoint from outside the container host.