Skip to content
MCP server

MCP Notes Server

Tiny local notes server that creates, lists and searches notes in a JSON file

Runs locallyStatus and history
Install
Pricing
Open source
Platforms
CLI, self-hosted
Runs
Locally
Version
1.0.0
Listing updated
today

Similar MCP servers

About MCP Notes Server

MCP Notes Server is an open-source MCP server for knowledge and memory. It runs locally on your machine and is started by your AI client.

Everything lives in one plain notes.json file next to the script, written atomically so a crash does not leave half a file. There is no database, cloud service or account, and the server makes no network calls.

It is a single Python file of roughly 150 lines built on the official MCP SDK's FastMCP API, and the author presents it as a starter pattern to copy and adapt rather than a hardened service. The requirements pin the 1.x SDK because 2.x renamed FastMCP. There is no delete tool and no authentication or locking beyond the atomic replace, which the README states openly.

It speaks stdio, so it works with Claude Desktop or any host that launches a command. The README includes a smoke test and an end-to-end test over the real protocol. The author also sells a larger paid template pack, but this server is MIT licensed.

Install

Run in a terminal

claude mcp add mcp-notes-server -- npx -y https://github.com/bradraylucas-eng/mcp-notes-server/releases/download/v1.0.0/mcp-notes-server.mcpb

Add to claude_desktop_config.json

{
  "mcpServers": {
    "mcp-notes-server": {
      "command": "npx",
      "args": [
        "-y",
        "https://github.com/bradraylucas-eng/mcp-notes-server/releases/download/v1.0.0/mcp-notes-server.mcpb"
      ]
    }
  }
}
Install in CursorOpens Cursor, which asks you to confirm. Or add it by hand:

Add to ~/.cursor/mcp.json

{
  "mcpServers": {
    "mcp-notes-server": {
      "command": "npx",
      "args": [
        "-y",
        "https://github.com/bradraylucas-eng/mcp-notes-server/releases/download/v1.0.0/mcp-notes-server.mcpb"
      ]
    }
  }
}
Install in VS CodeOpens VS Code, which asks you to confirm. Or add it by hand:

Add to .vscode/mcp.json

{
  "servers": {
    "mcp-notes-server": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "https://github.com/bradraylucas-eng/mcp-notes-server/releases/download/v1.0.0/mcp-notes-server.mcpb"
      ]
    }
  }
}

Add to ~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "mcp-notes-server": {
      "command": "npx",
      "args": [
        "-y",
        "https://github.com/bradraylucas-eng/mcp-notes-server/releases/download/v1.0.0/mcp-notes-server.mcpb"
      ]
    }
  }
}

Add to your client's MCP settings (most use this shape)

{
  "mcpServers": {
    "mcp-notes-server": {
      "command": "npx",
      "args": [
        "-y",
        "https://github.com/bradraylucas-eng/mcp-notes-server/releases/download/v1.0.0/mcp-notes-server.mcpb"
      ]
    }
  }
}

Using several servers? Build one config file with the MCP config generator.

Tools this server provides (3)

Taken from the project documentation; the running server may differ.

create_note
Creates a note with a title and body and returns the saved record
list_notes
Lists saved notes, newest first
search_notes
Case-insensitive keyword search across titles and bodies

What it does

Create notes
Saves a note with a title up to 120 characters and a body up to 10,000.
List notes
Returns saved notes newest first with a configurable limit of 1 to 500.
Keyword search
Case-insensitive search across titles and bodies.
Local JSON storage
Notes stay in a readable file on your machine.
Input validation
Each tool checks and caps its inputs.
Single-file design
About 150 lines, intended to be read and adapted.

Good for

  • Give an assistant a persistent scratchpad between chats
  • Learn how a minimal Python MCP server is structured
  • Use as a base for building your own stdio tools
  • Prototype note capture without any hosted service

Pricing

Open source

Free and MIT licensed

MCP Notes Server FAQ

Where are notes stored?

In notes.json, created automatically beside server.py.

Can it delete notes?

No, there is deliberately no delete tool.

Is it production ready?

The README calls it a learning and prototyping base with no authentication or concurrency locking beyond atomic file replacement.

What licence applies?

MIT.

Is MCP Notes Server free?

Yes. MCP Notes Server is open source, so you can use and self-host it for free.

How do I add MCP Notes Server to Claude Code?

Run this command in your terminal: claude mcp add mcp-notes-server -- npx -y https://github.com/bradraylucas-eng/mcp-notes-server/releases/download/v1.0.0/mcp-notes-server.mcpb

What are the best alternatives to MCP Notes Server?

The closest alternatives to MCP Notes Server are Codebase Memory, XERJ, Ha MCP, Claude Code Ultimate Guide and Concord MCP.

Where this comes from

  • Description: written from the project's README.
  • Install steps: from the official MCP Registry entry.

How AIPoweredBot checks servers