convez.ai
MCP ServerProdutividadeAvançado
michaelkrauty

MCP Notes

michaelkrauty/mcp-notes

Gestão inteligente de notas com busca semântica e histórico Git

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor 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-notes

1 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

Estrelas
1
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 2 semanas
Versão
v1.3.17
Issues abertas
1
Contribuidores
1

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/embeddings endpoint; 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)

ToolDescription
create_noteCreate note with auto-generated UUID
read_noteRead note by UUID
update_noteUpdate title, content, tags, or category
delete_noteDelete note (keeps git history)

Search (3)

ToolDescription
search_notesHybrid semantic + keyword search with filters
list_notesList notes with tag/category filters
find_similar_notesFind semantically similar notes

Versioning (2)

ToolDescription
get_note_historyGit commit history for a note
restore_note_versionRestore note to previous commit

Links (1)

ToolDescription
get_note_linksOutgoing, incoming (backlinks), and broken links

Tags (3)

ToolDescription
list_tagsAll tags with note counts
rename_tagRename tag across all notes
merge_tagsMerge multiple tags into one

Categories (2)

ToolDescription
list_categoriesCategory hierarchy with counts
move_categoryMove/rename a category

Glossary (6)

ToolDescription
add_glossary_entryAdd term with expansion, definition, domain
lookup_termExact lookup by term or alias
search_glossarySemantic glossary search
list_glossaryList entries with optional domain filter
update_glossary_entryModify entry metadata
delete_glossary_entryDelete entry

Facts (11)

ToolDescription
add_factAdd SPO triple with source tracking
add_facts_batchBatch import facts
update_factUpdate fact metadata
delete_factDelete fact and sources
query_factsQuery by subject/predicate/object
get_entityAll facts involving an entity
list_factsList fact summaries
search_factsSemantic fact search
index_factsIndex facts for search
find_connectionsBFS graph traversal between entities
get_neighborsImmediate entity connections

Integrity (4)

ToolDescription
get_facts_with_stale_sourcesFacts with deleted/modified sources
get_source_statisticsSource integrity stats
check_fact_integrityCheck specific fact's sources
revalidate_fact_sourcesReset sources after verification

Health (2)

ToolDescription
reindex_notesForce full reindex
check_note_healthValidate 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

DataLocation
Notes{NOTES_DIR}/notes/ (default ~/notes/notes/)
UUID index{NOTES_DIR}/.index/
VectorsQdrant 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

VariableDefaultDescription
NOTES_DIR~/notesNotes storage directory
NOTES_GIT_ENABLEDtrueEnable git versioning
NOTES_GIT_USER_NAMENotes MCPGit commit author
NOTES_GIT_USER_EMAILnotes@localhostGit commit email
NOTES_AUTO_INDEXtrueAuto-index on startup
NOTES_COLLECTION_PREFIXnotesQdrant 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 index
  • notes://tags - All tags with counts
  • notes://categories - Category hierarchy
  • notes://recent - Last 20 modified notes
  • notes://orphans - Notes with no backlinks
  • notes://broken-links - Broken reference summary
  • notes://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)
Ver o original no GitHub

Bom para

Relacionados