notes MCP server
Commit Nov 4, 2026An MCP server that lets an AI client capture, search, update, and delete project notes using a MongoDB backend.
Also known as manish0502/mcp-notes
- Stars
- 0
- Tools
- 4
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 4, 2026
- License
- MIT
What is notes MCP?
notes is an MCP server that lets an AI client capture, search, update, and delete project notes using a MongoDB backend. It exposes 4 tools, such as add_note, search_notes, update_note.
Summary generated from the project's README
About notes MCP server
Managing project documentation and quick captures from within an AI client is what mcp-notes enables. This server provides a structured way for models to interact with a MongoDB backend to store and retrieve information. It is designed for developers who want to give their AI assistants a persistent memory for project-specific details using tools like add_note, search_notes, update_note, and delete_note.
Users can connect to the server via stdio for local use with Claude Desktop or Claude Code, or through an Express-based HTTP transport for remote or scalable setups. The system utilizes Mongoose for data modeling and Zod for strict argument validation. It also exposes read-only resources such as notes://all and notes://tags, along with a review_open_notes prompt to help seed conversations. To function, a MongoDB instance must be running on localhost:27017 or a custom URI provided via environment variables.
What you can do with it
- 1Reviewing current project contextA developer can use a predefined template to have the AI analyze all currently open notes.
- 2Accessing organized note metadataThe client can pull a list of all available tags to understand how notes are categorized.
Written from the project's README. Every use case is checked against a quote from it.
notes MCP tools 4
Detected from the READMEadd_notesearch_notesupdate_notedelete_note
Configuration
MCP_TRANSPORTMONGODB_URI
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablemanish0502/mcp-notes is public and reachablegithub.com/manish0502/mcp-notes ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-04github.com/manish0502/mcp-notes ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model4 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubmcp-notes
An MCP server for capturing and querying project notes — backed by MongoDB, served over stdio or Express. A complete, minimal reference implementation of all three MCP primitives.
Stack: MongoDB + Express + Node (TypeScript), Mongoose ODM.
Demo
https://github.com/user-attachments/assets/b49dcb2d-029e-42d3-a3ce-12cb7e0d773f
Three minutes in the MCP Inspector: listing the tools, calling them against MongoDB, reading resources, and the raw JSON-RPC behind each call.
What MCP actually gives you
Three primitives, and who controls each one is the part people get wrong:
| Primitive | Controlled by | Purpose | Here |
|---|---|---|---|
| Tools | the model | actions with side effects | add_note, search_notes, update_note, delete_note |
| Resources | the application | read-only data addressed by URI | notes://all, notes://tags |
| Prompts | the user | reusable templates, usually a slash command | review_open_notes |
Tools are the only primitive that can change anything. A resource is read, never called. A prompt returns messages that seed a conversation — not an answer.
How a request flows
Claude Code / Desktop
│ JSON-RPC over stdio (or HTTP POST /mcp)
▼
src/transports/ stdio.ts │ http.ts (Express)
│
▼
src/mcp/server.ts tools · resources · prompts
│ zod validates arguments before any handler runs
▼
src/services/ business logic — knows Mongo, knows nothing about MCP
│
▼
src/models/ Mongoose schema → plain DTO
│
▼
MongoDB
Each layer only knows the one below it. The service has no idea it is being called over a protocol, which is why it can be tested without one.
The tools, and their annotations
annotations are hints to the client about what a tool does. They are advisory, not
enforced — but clients use them to decide what needs human approval and what is safe to
cache. Omit them and every caller must assume the worst.
| Tool | readOnly | destructive | idempotent | Why |
|---|---|---|---|---|
add_note |
no | no | no | writes, but only inserts — nothing is lost. Twice = two notes |
search_notes |
yes | – | – | safe to call freely, safe to cache |
update_note |
no | no | yes | overwrites fields; same patch twice = same end state |
delete_note |
no | yes | yes | the one tool a client should confirm first |
Quick start
MongoDB must be running on localhost:27017.
npm install
npm test
npm run dev
Set MONGODB_URI to use a different database (default mongodb://127.0.0.1:27017/mcp_notes).
Try it with the MCP Inspector
npm run inspect
Register it with Claude Code or Claude Desktop
{
"mcpServers": {
"notes": {
"command": "npx",
"args": ["tsx", "/absolute/path/to/mcp-notes/src/index.ts"],
"env": { "MONGODB_URI": "mongodb://127.0.0.1:27017/mcp_notes" }
}
}
}
Or run it over HTTP
MCP_TRANSPORT=http PORT=3100 npm run dev
curl -s -X POST http://127.0.0.1:3100/mcp -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
The HTTP mode is stateless: a fresh server per request, no session id, so it scales
horizontally with no sticky routing. There is also a plain GET /healthz that reports
whether Mongo is reachable.
Layout
| Path | Job |
|---|---|
src/config/db.ts |
the only file that knows the Mongo URI |
src/models/note.model.ts |
Mongoose schema; converts documents to plain DTOs |
src/services/note.service.ts |
business logic and queries. No MCP here |
src/mcp/schemas.ts |
zod input shapes — these become the published JSON Schema |
src/mcp/server.ts |
the MCP surface: tools, resources, prompts |
src/transports/stdio.ts |
what Claude Code spawns |
src/transports/http.ts |
Express + streamable HTTP |
src/index.ts |
composition root: connect Mongo, pick a transport |
test/note.service.test.ts |
queries against real MongoDB |
test/mcp-server.test.ts |
a real MCP client talking to the server in-process |
Five things worth knowing
1. stdout is the protocol channel. One console.log in a stdio server corrupts the
JSON-RPC stream and the client disconnects with a parse error. All diagnostics go to
stderr.
2. isError is not an exception. A bad note id returns { isError: true } with a
readable message — the call succeeded, the tool reported a problem, and the model can
read it and retry. Throwing instead looks like a server fault.
3. The SDK validates arguments for you. The zod shapes in src/mcp/schemas.ts become
JSON Schema for tools/list and are enforced before your handler runs. A call missing a
required field never reaches your code — it comes back as an isError result naming the
offending field. You never hand-validate tool arguments.
4. Prompt arguments are strings. Tools accept rich JSON Schema types; prompts
transmit arguments as strings only. That is why reviewPromptShape exists separately
instead of reusing the search shape.
5. .describe() is prompt engineering. Every description in the zod shape is
published to the model and is how it decides which tool to call. Vague descriptions are
the most common reason a correct tool never gets used.
Tests
36 tests, no mocks. test/note.service.test.ts runs real queries against a dedicated
database that is wiped between tests. test/mcp-server.test.ts wires a genuine MCP
Client to the server over InMemoryTransport — the same code path as stdio, without
spawning a process. That second file is the most valuable test to write for any MCP
server: it catches schema mistakes and missing annotations that service-level unit tests
cannot see.
They need a local mongod. For CI, add a MongoDB service container or swap in
mongodb-memory-server.
License
MIT
notes MCP questions
What tools does notes MCP provide?
It exposes 4 tools, including add_note, search_notes, update_note, delete_note.
What tools are available in mcp-notes?
The server provides tools to add, search, update, and delete notes.
How can I change the database connection string?
You can set the MONGODB_URI environment variable to use a different database.
Does the server support HTTP transport?
Yes, the server can be run over HTTP using Express, which allows for stateless horizontal scaling.
What are the available resources?
The server provides read-only resources for all notes and tags via URI.