# MCP Notes Server

> MCP Notes Server is an open-source MCP server for knowledge and memory. Tiny local notes server that creates, lists and searches notes in a JSON file. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Pricing:** Open source
- **Platforms:** CLI, self-hosted
- **Repository:** https://github.com/bradraylucas-eng/mcp-notes-server
- **MCP Registry name:** io.github.bradraylucas-eng/mcp-notes-server
- **Categories:** [knowledge and memory](https://ai-powered.com/categories/knowledge-and-memory), [productivity](https://ai-powered.com/categories/productivity)
- **Listing updated:** 2026-11-18

## About

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.

## Features

- **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

## Install

### Claude Code (Terminal)

```sh
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
```

### Claude Desktop (claude_desktop_config.json)

```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"
      ]
    }
  }
}
```

### Cursor (~/.cursor/mcp.json)

```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"
      ]
    }
  }
}
```

### VS Code (.vscode/mcp.json)

```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"
      ]
    }
  }
}
```

### Windsurf (~/.codeium/windsurf/mcp_config.json)

```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"
      ]
    }
  }
}
```

### Other clients (your client's MCP settings (most use this shape))

```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"
      ]
    }
  }
}
```

## Tools

- `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

## 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.

## Alternatives

- [Codebase Memory](https://ai-powered.com/mcp/codebase-memory): Codebase Memory is an open-source MCP server for knowledge and memory.
- [XERJ](https://ai-powered.com/mcp/xerj): XERJ is an open-source MCP server for knowledge and memory.
- [Ha MCP](https://ai-powered.com/mcp/ha-mcp): Ha MCP is an open-source MCP server for productivity.
- [Claude Code Ultimate Guide](https://ai-powered.com/mcp/claude-code-ultimate-guide): Claude Code Ultimate Guide is an open-source MCP server for ai models and llm tooling.
- [Concord MCP](https://ai-powered.com/mcp/concord-mcp): Concord MCP is a freemium MCP server for developer tools.
- [Nautilus Compass Memory](https://ai-powered.com/mcp/nautilus-compass-memory): Nautilus Compass Memory is an open-source MCP server for knowledge and memory.
- [NeuroStack](https://ai-powered.com/mcp/neurostack): NeuroStack is a freemium MCP server for knowledge and memory.
- [note1](https://ai-powered.com/mcp/note1): note1 is an MCP server for productivity.

---
Source: https://ai-powered.com/mcp/mcp-notes-server
