Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@mcp-notes-server save a note about the deployment decision and tag it infra"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A small MCP server that gives an AI agent a notebook: write notes, search them full text, organise them with tags. Written in plain Python 3.11, standard library only, no dependencies to install and nothing to run in the background.
An agent forgets everything between sessions. Files work for long documents, but not for the hundreds of small facts that pile up during work: a decision, a hostname, why an approach was dropped. This server keeps them in one SQLite file and makes them findable in one tool call.
It is also a compact, readable reference of what a Model Context Protocol server actually is:
JSON-RPC 2.0 over stdin and stdout, an initialize handshake, and a list of typed tools.
Related MCP server: Notes MCP Server
git clone https://github.com/Aliaksandr-Andronchyk/mcp-notes-server.git
cd mcp-notes-server
python3 -m mcp_notes --helpPython 3.11 or newer, with SQLite compiled with FTS5 (the default on macOS and Debian).
One line:
claude mcp add notes -- python3 -m mcp_notesRun it from the clone, or add --db ~/.mcp-notes/notes.db and use an absolute path to
python3 if you launch from elsewhere. The equivalent entry in .mcp.json or
claude_desktop_config.json:
{
"mcpServers": {
"notes": {
"command": "python3",
"args": ["-m", "mcp_notes", "--db", "~/.mcp-notes/notes.db"],
"cwd": "/path/to/mcp-notes-server"
}
}
}Check it with claude mcp list, then ask the agent to "save a note about X" or
"search my notes for X".
Tool | What it does |
| Save a note: |
| Full text search over title and body, optional |
| Recently changed notes first, optional |
| Read one note in full by |
| Change |
| Delete by |
| Every tag in use with the number of notes carrying it. |
Search treats each word as a prefix, so migra finds migrations, and requires all words to
match. Search text is tokenized and quoted before it reaches SQLite, so FTS5 operators typed by
a user are matched as ordinary words instead of changing the query. Tags are lowercased, a
leading # is stripped, and duplicates are dropped.
One SQLite file, ~/.mcp-notes/notes.db by default, overridden by --db or the MCP_NOTES_DB
environment variable. Notes live in an ordinary table; an FTS5 index is kept in sync by triggers,
so writes through any path stay searchable. Back it up by copying the file.
Useful for debugging without a client attached:
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"add_note","arguments":{"title":"hello","tags":["demo"]}}}' \
| python3 -m mcp_notes --db /tmp/notes.dbLogs go to stderr, because stdout carries the protocol and has to stay clean.
pip install pytest
python3 -m pytest tests -q31 tests covering storage, search behaviour, the JSON-RPC layer and a full stdio session.
MIT.
Save a new note with a title, an optional body and optional tags.
| Name | Required | Description | Default |
|---|---|---|---|
| body | No | Note text. | |
| tags | No | Tags, lowercased automatically, a leading # is stripped. | |
| title | Yes | Short title, required. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions that body and tags are optional, but it does not disclose mutation side effects, return behavior, or failure modes. Tag normalization is mentioned only in the schema, not in the description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence with no filler, front-loading the core action ('Save') and then listing the optional parameters. Every word contributes to understanding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple three-parameter creation tool, the schema covers all parameters well, but the description lacks usage guidance and behavioral context. With no annotations and no output schema, an agent gets only the bare minimum needed to invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents title, body, and tags. The description adds marginal framing by identifying body and tags as optional, but it does not meaningfully expand on the schema's parameter details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Save' and the resource 'a new note', which distinguishes creation from the sibling operations search_notes, list_notes, get_note, update_note, and delete_note. It also signals the operation is for creating, not modifying or retrieving.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The word 'new' implies this tool is for creating rather than updating, but the description does not explicitly say when to use it over update_note or how it relates to the other sibling tools. Usage context is implied rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a note by id.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It states only 'Delete a note by id,' which essentially restates the tool name and the action. It does not mention that the operation is irreversible, whether it fails on non-existent ids, or what the return value is. This is minimal disclosure for a destructive action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no filler. The key information (delete action and id) is front-loaded. It is appropriately concise for such a simple operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has one parameter, no output schema, and no annotations, so the description must cover basic runtime behavior. It does not mention whether the action is permanent, how errors are reported (e.g., 404 for missing id), or the response format (success vs. empty). This leaves the agent uncertain about expected outcomes.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate for the schema's lack of detail. The description says 'by id' but does not explain that 'id' refers to the note ID obtained from list_notes or get_note, nor any format or range constraints. With a single integer parameter, the description should at least clarify its origin, which is missing.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the verb 'Delete' and the resource 'note' precisely, with the id as the target. It clearly distinguishes from siblings like get_note and update_note by its destructive action. However, it doesn't explicitly differentiate from other delete-like operations or mention cascading effects, so it's not a perfect 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage context is implied: use this tool when you want to permanently remove a note. There is no explicit guidance on when not to use it (e.g., when you only need to fetch or modify), nor any reference to alternative tools like get_note or update_note. The description leaves the decision to the agent's inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read one note in full by its id.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden of indicating behavior. It communicates that the operation is read-only and returns the complete note, but it does not disclose behavior for missing IDs, permission issues, or response format details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, tightly worded sentence. It states the action and the key distinguishing constraint with no filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter read operation, this is largely sufficient: the agent knows to pass a note ID and expects the full note in return. It would be more complete with a note about not-found or error behavior, but no output schema makes that gap less critical.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has a bare integer 'id' parameter with 0% description coverage. The phrase 'by its id' confirms the purpose of the parameter, but it adds no detail about where the ID comes from, what it refers to beyond the obvious note ID, or any formatting constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'read one note in full by its id.' This clearly distinguishes it from sibling tools like search_notes and list_notes, which search or list rather than fetch a single full note.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It implies the appropriate use case: fetching a known note by ID. However, it does not explicitly state when to prefer this over list_notes, search_notes, or update_note, nor does it mention any exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List notes by last change, optionally filtered by tag.
| Name | Required | Description | Default |
|---|---|---|---|
| tag | No | ||
| limit | No | Max results, default 20. | |
| offset | No | Skip this many, default 0. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the burden. It discloses the ordering and filter behavior but does not mention pagination (though limit/offset are in schema), potential performance implications, or what happens when no notes match. It's a read-only operation, but that's inferred. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One concise sentence, well-structured, with key attributes (ordering, filter) front-loaded. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only list tool with optional filters and pagination, the description is adequate but leaves minor gaps: it doesn't mention what is returned (e.g., note object vs metadata), and given no output schema, that info is missing. It could specify that it returns note summaries or full notes, but overall it's sufficient for an agent to call it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 'tag' with no descriptionstitution, but 'limit' and 'offset' have descriptions. With 67% coverage, the description adds optional filter context for 'tag' but doesn't elaborate on semantics beyond the schema. Baseline 3 is appropriate given partial coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb ('List') and resource ('notes') and specifies ordering ('by last change') and an optional filter ('by tag'). It is distinct from siblings like search_notes (which implies search) and get_note, though it doesn't explicitly differentiate them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies a simple listing use case and distinguishes it from search_notes by using 'list' versus 'search'. However, it doesn't explicitly state when to use this over search_notes or other list-like tools, nor does it mention alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
All tags in use with the number of notes carrying each.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It clearly indicates a non-mutating read operation (listing tags) and discloses the output nature (tags and counts). It does not explicitly state 'read-only', but the phrasing 'All tags in use' implies a query without side effects. It omits potential caveats like result size or pagination, but for a zero-parameter tool this is a minor gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no waste. It front-loads the key information (all tags, counts) and provides sufficient detail without redundancy. Every word contributes to the meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, no-input-tool with no output schema, the description is complete. It tells the agent exactly what will be returned (all tags and their note counts). There is no missing information that would prevent correct invocation or interpretation, making it fully adequate for its simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool accepts zero parameters, so schema coverage is 100% (no params to document). The description adds meaning by specifying what the output represents (tags and their note counts), which is exactly what an agent needs. With 0 parameters, the baseline is 4, and the description enhances the semantics by defining the result's content.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states what the tool returns: all tags in use and the note count per tag. This clearly identifies the resource (tags) and the operation (listing with counts), which distinguishes it from sibling tools like list_notes or search_notes that deal with notes rather than tags.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for retrieving a tag frequency overview but provides no explicit guidance on when to use this tool versus alternatives like list_notes or search_notes. There is no mention of edge cases (e.g., tags with zero notes) or conditions that would make this tool preferable. It is self-evident but not explicitly differentiated from siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Full text search over titles and bodies, newest ranking first, optionally narrowed to one tag. Every word is a prefix match.
| Name | Required | Description | Default |
|---|---|---|---|
| tag | No | Only notes carrying this tag. | |
| limit | No | Max results, default 20. | |
| query | Yes | Words to look for. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden and does well: it discloses newest-first ranking, prefix-match semantics for every word, and optional tag narrowing. It does not mention return shape or read-only status, but the core behaviors an agent needs are present.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with no filler. The search scope is front-loaded, followed by ranking, tag filtering, and matching semantics. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a search tool with a well-covered schema, the description is largely complete: it specifies what is searched, how results are ranked, how tags narrow results, and how matching works. It does not describe the output payload, but no output schema exists and the absence is not a major gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description adds real value: 'Every word is a prefix match' clarifies how the query parameter behaves, and 'optionally narrowed to one tag' adds precision to the tag parameter beyond its schema description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: full-text search over note titles and bodies. It also adds scope and behavior (newest first, optional tag narrowing) that distinguish it from siblings like list_notes and get_note, which are listing/retrieval tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use it: when searching note content by words. However, it does not explicitly name alternatives or state when not to use it, leaving the choice versus list_notes/get_note to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Change title, body or tags of a note. Omitted fields stay as they are.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| body | No | ||
| tags | No | ||
| title | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It usefully states that omitted fields remain unchanged, but does not say whether supplied values fully overwrite existing ones, how empty strings are handled, what happens to the note's other metadata, or what the response looks like.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with no filler. The primary action is front-loaded, and the most important partial-update behavior is stated immediately in the second sentence.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple update operation, the description covers the essential partial-update behavior and names the editable fields. Still, with no annotations and no output schema, it leaves gaps around required id usage, overwrite behavior, return value, and error conditions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It names title, body, and tags as mutable parameters, which adds some meaning to the bare property names, but it does not explain the id parameter's role, tag list semantics, or edge-case behavior beyond 'omitted fields stay as they are'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific action ('Change') on a specific resource ('a note') and names the affected fields (title, body, tags). This clearly differentiates update_note from its siblings add_note, get_note, delete_note, and list_notes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The second sentence implies partial-update semantics: omitted fields are left unchanged. However, it gives no explicit guidance on when to use this tool over alternatives, prerequisites, or conditions under which it should not be used.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.0add_notedelete_noteget_notelist_noteslist_tagssearch_notesupdate_noteScored across 7 tools
Each tool maps to a distinct action and resource: CRUD operations on notes, search, and tag listing. There is no overlap or ambiguity between tools.
All tools follow a clear verb_noun pattern: add_note, search_notes, list_notes, get_note, update_note, delete_note, list_tags. Singular/plural variation is natural and does not harm predictability.
Seven tools is a well-scoped size for a notes server. Each tool serves a necessary purpose without redundancy or bloat.
The note lifecycle is fully covered with create, read, list, update, and delete, plus search and tag management. There are no obvious dead ends or missing core operations.
Cross-session, cross-device memory for your agent: remember and recall notes. No key to start.
Persistent memory for AI agents. Search and store durable facts, preferences and decisions.
Persistent memory for AI agents. Search, store, and recall across sessions.
Persistent docs and memory for AI agents — read, write, organize & search a shared workspace.
