MCP Notes
michaelkrauty/mcp-notes
Gestão inteligente de notas com busca semântica e histórico Git
Ver no GitHubServidor MCP para gestão de conhecimento pessoal com busca semântica, versionamento Git e grafo de conhecimento. Oferece CRUD de notas markdown, wiki links, tags, categorias e glossário com histórico completo de alterações.
Instalação
npx convez-ai michaelkrauty/mcp-notes1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Construir base de conhecimento pessoal com inter-conexões entre notas
- Pesquisar notas por significado semântico, não apenas palavras-chave
- Manter histórico e recuperar versões anteriores de notas
- Organizar conhecimento com tags, categorias e glossário compartilhado
Veredito

Solução robusta e completa para PKM (Personal Knowledge Management) que demanda setup técnico (Qdrant, embedding API, Python 3.12+). Ideal para usuários que valorizam busca semântica, versionamento e grafo de conhecimento; não é plug-and-play, mas oferece funcionalidades avançadas que justificam a complexidade.
README
A tradução para o português deste README ainda está na fila.
mcp-notes
MCP server for personal knowledge management with semantic search, git versioning, and knowledge graph capabilities.
Prerequisites
- Python 3.12+
- Linux or macOS (uses POSIX file locking via vector-core; not compatible with Windows)
- Qdrant vector database (default:
localhost:6333) - An OpenAI-compatible embedding API (e.g., llama.cpp, Ollama, or any
/v1/embeddingsendpoint; default:localhost:8080) - git (must be on PATH for versioning features)
Installation
Requires vector-core.
pip install git+https://github.com/michaelkrauty/vector-core.git@v1.2.7
pip install git+https://github.com/michaelkrauty/mcp-notes.git
Or clone both repos and install locally:
git clone https://github.com/michaelkrauty/vector-core.git
git clone https://github.com/michaelkrauty/mcp-notes.git
pip install -e vector-core/
pip install -e mcp-notes/
Quick Start
# Register with Claude Code:
claude mcp add notes -- mcp-notes
# Or add to your MCP client config (e.g., claude_desktop_config.json):
# {
# "mcpServers": {
# "notes": {
# "command": "mcp-notes",
# "env": {
# "VECTOR_QDRANT_URL": "http://localhost:6333",
# "VECTOR_EMBEDDING_URL": "http://localhost:8080",
# "VECTOR_EMBEDDING_MODEL": "your-model-name"
# }
# }
# }
# }
Features
- Note Management: CRUD operations on markdown notes with YAML frontmatter
- Semantic Search: Hybrid dense + sparse vector search via Qdrant
- Git Versioning: Automatic commits on changes, full history with
--follow - Wiki Linking:
[[uuid]]syntax for inter-note references with backlink tracking - Tags & Categories: Flexible organization with tag management tools
- Glossary: Shared term definitions with aliases and domains
- Fact Graph: Subject-predicate-object triples with source tracking
Tools (38 total)
Notes (4)
| Tool | Description |
|---|---|
create_note | Create note with auto-generated UUID |
read_note | Read note by UUID |
update_note | Update title, content, tags, or category |
delete_note | Delete note (keeps git history) |
Search (3)
| Tool | Description |
|---|---|
search_notes | Hybrid semantic + keyword search with filters |
list_notes | List notes with tag/category filters |
find_similar_notes | Find semantically similar notes |
Versioning (2)
| Tool | Description |
|---|---|
get_note_history | Git commit history for a note |
restore_note_version | Restore note to previous commit |
Links (1)
| Tool | Description |
|---|---|
get_note_links | Outgoing, incoming (backlinks), and broken links |
Tags (3)
| Tool | Description |
|---|---|
list_tags | All tags with note counts |
rename_tag | Rename tag across all notes |
merge_tags | Merge multiple tags into one |
Categories (2)
| Tool | Description |
|---|---|
list_categories | Category hierarchy with counts |
move_category | Move/rename a category |
Glossary (6)
| Tool | Description |
|---|---|
add_glossary_entry | Add term with expansion, definition, domain |
lookup_term | Exact lookup by term or alias |
search_glossary | Semantic glossary search |
list_glossary | List entries with optional domain filter |
update_glossary_entry | Modify entry metadata |
delete_glossary_entry | Delete entry |
Facts (11)
| Tool | Description |
|---|---|
add_fact | Add SPO triple with source tracking |
add_facts_batch | Batch import facts |
update_fact | Update fact metadata |
delete_fact | Delete fact and sources |
query_facts | Query by subject/predicate/object |
get_entity | All facts involving an entity |
list_facts | List fact summaries |
search_facts | Semantic fact search |
index_facts | Index facts for search |
find_connections | BFS graph traversal between entities |
get_neighbors | Immediate entity connections |
Integrity (4)
| Tool | Description |
|---|---|
get_facts_with_stale_sources | Facts with deleted/modified sources |
get_source_statistics | Source integrity stats |
check_fact_integrity | Check specific fact's sources |
revalidate_fact_sources | Reset sources after verification |
Health (2)
| Tool | Description |
|---|---|
reindex_notes | Force full reindex |
check_note_health | Validate note structure, find errors |
Data Model
Note
---
id: {uuid}
title: Note Title
created: 2024-01-01T00:00:00Z
modified: 2024-01-05T12:00:00Z
tags: [tag1, tag2]
links: [linked-uuid]
---
Markdown content with [[uuid]] links.
Fact (SPO Triple)
subject: "Ada Lovelace" (type: person)
predicate: "works_at"
object: "Babbage Labs" (type: organization)
context: "as lead engineer"
confidence: 1.0
valid_from/to: date range
sources: [{type: note, id: uuid, location: "paragraph 3"}]
Storage
| Data | Location |
|---|---|
| Notes | {NOTES_DIR}/notes/ (default ~/notes/notes/) |
| UUID index | {NOTES_DIR}/.index/ |
| Vectors | Qdrant collection notes_{hash} |
| Git repo | {NOTES_DIR}/.git/ |
| Facts & glossary | ~/.local/share/vector-core/ (configurable via VECTOR_SHARED_DATA_DIR) |
NOTES_DIR (default ~/notes) is the base directory. Actual note files live in the notes/ subdirectory within it. The base directory also contains .index/, .git/, and .locks/.
Notes stored as {slug}-{uuid}.md organized by category subdirectories.
Configuration
| Variable | Default | Description |
|---|---|---|
NOTES_DIR | ~/notes | Notes storage directory |
NOTES_GIT_ENABLED | true | Enable git versioning |
NOTES_GIT_USER_NAME | Notes MCP | Git commit author |
NOTES_GIT_USER_EMAIL | notes@localhost | Git commit email |
NOTES_AUTO_INDEX | true | Auto-index on startup |
NOTES_COLLECTION_PREFIX | notes | Qdrant collection prefix |
Plus inherited vector-core settings (VECTOR_QDRANT_URL, VECTOR_EMBEDDING_URL, etc.).
Search Query Syntax
# Filter by tag
tag:project-x
# Exclude a tag
-tag:archived
# Filter by category (exact match)
category:work/projects
# Date filters
after:2024-01-01
before:2024-06-30
# Title search
title:meeting notes
# Combined
project tag:active category:work after:2024-01-01
MCP Resources
Static data endpoints:
notes://index- Full note indexnotes://tags- All tags with countsnotes://categories- Category hierarchynotes://recent- Last 20 modified notesnotes://orphans- Notes with no backlinksnotes://broken-links- Broken reference summarynotes://parse-errors- Notes that failed to parse
Dependencies
Requires vector-core components:
- EmbeddingClient, GlobalVocabulary (search)
- QdrantStorage (storage)
- GlossaryStore, FactStore (knowledge graph)
External libraries:
- GitPython (versioning)