notes-mcp
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
notes-mcp
A minimal MCP (Model Context Protocol) server and client, built to learn the protocol from the ground up.
Manages plain-text notes on disk and exposes them via MCP's three core primitives: resources, tools, and prompts. Includes an interactive CLI agent that uses Gemini's function calling to decide which MCP tools to invoke based on natural language.
Why
Built as a hands-on exercise to understand MCP architecture before reaching for higher-level agent frameworks. Every piece — server, transport, client, LLM integration — is implemented manually(with a built of help from Claude).
Related MCP server: approveit MCP Server
Architecture
┌──────────────────┐ stdio ┌──────────────────┐
│ agent_client.py │◄──────────────────────► │ notes_server.py │
│ │ JSON-RPC (MCP) │ │
│ - discovers │ │ Resources: │
│ capabilities │ │ - notes://list │
│ - sends to │ │ │
│ Gemini │ │ Tools: │
│ - executes │ │ - create_note │
│ tool calls │ │ - read_note │
└────────┬─────────┘ │ - delete_note │
│ │ - search_notes │
▼ │ │
┌─────────────┐ │ Prompts: │
│ Gemini API │ │ - summarize_note│
└─────────────┘ └──────────────────┘Setup
git clone https://github.com/suhail1060/notes-mcp.git
cd notes-mcp
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
export GEMINI_API_KEY="your-key-here"Usage
Inspect the server directly (no LLM needed):
mcp dev server/notes_server.pyOpens a browser UI to explore resources, tools, and prompts manually.
Run the interactive agent:
python client/agent_client.pyType natural language requests; Gemini picks the right tool and the client executes it via MCP.
You: create a note called groceries with eggs and milk
[calling tool: create_note({'title': 'groceries', 'content': 'eggs and milk'})]
[tool result: Created note: groceries.md]
Assistant: I've created the note "groceries.md" with your list.Run tests:
pytest tests/ -vMCP concepts covered
Resources — read-only data (
notes://list) the client can fetchTools — actions with side effects (
create_note,read_note,delete_note,search_notes)Prompts — reusable prompt templates (
summarize_note)Transport — stdio-based JSON-RPC between client and server
Client discovery — capability negotiation via
session.initialize()andlist_tools()/list_resources()/list_prompts()LLM tool-calling loop — converting MCP tool schemas to Gemini function declarations, executing the chosen tool, and feeding results back for a final response
Project structure
notes-mcp/
├── server/
│ └── notes_server.py # MCP server: resources, tools, prompts
├── client/
│ ├── agent_client.py # Interactive CLI using Gemini + MCP
│ └── llm_agent.py # Gemini <-> MCP tool schema conversion
├── tests/
│ └── test_notes_server.py
├── data/notes/ # Notes storage (gitignored)
└── pyproject.tomlLicense
MIT License — see LICENSE for details.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Persistent memory layer for AI tools. Save and recall notes across Claude and other MCP clients.
MCP-native notes and memory for ChatGPT, Claude, and other AI tools.
Agent-native notes, tasks, dev-docs, vaults, sync & handoffs. MCP + OpenAPI dual surface.
Save notes in seconds. Your AI can then search, read, write and tag them over MCP.
Related MCP Servers
- -licenseCqualityDmaintenanceEnables creating and managing text notes through MCP resources and tools. Provides note creation capabilities and automatic summarization of all stored notes.1-
- -licenseNot gradedqualityNot gradedmaintenanceA simple notes system that allows creating, storing, and accessing text notes through MCP resources and tools, with built-in prompt support for generating summaries of stored notes.-
- AlicenseNot gradedqualityDmaintenanceA simple notes MCP server that enables creating, listing, and summarizing text notes via resources, tools, and prompts.MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to manage in-memory notes by listing, fetching, and creating notes through MCP tools over stdio.138 npmMIT