Markdown Notes MCP CLI
A powerful command-line interface for managing and searching through markdown notes using advanced semantic search powered by MCP (Model Context Protocol) and machine learning embeddings.
Potencialize seu agente
Instalação do publicador. Não é um endpoint do PlugMCP.
Host a copy with our keys and logs.
Ainda não há uma versão empacotada no registro. Siga o README do repositório.
URL remota ou um comando na sua máquina? Como as duas instalações diferem
Rodar no PlugMCP
A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.
AbrirDo publicador
A powerful command-line interface for managing and searching through markdown notes using advanced semantic search powered by MCP (Model Context Protocol) and machine learning embeddings.
A semantic search system for Markdown notes with Model Context Protocol (MCP) server integration. Build searchable embeddings indexes from your Markdown files and expose them via JSON-RPC 2.0 over stdio for LLM integrations.
Clone or navigate to your project directory:
cd C:\Users\Devarshi\PycharmProjects\markdown-notes-mcp
Create and activate virtual environment:
python -m venv .venv
.venv\Scripts\activate # Windows
# source .venv/bin/activate # Linux/Mac
Install dependencies:
pip install -r requirements.txt
Verify installation:
python mcp_cli_fixed.py --help
# Search for notes
python mcp_cli_fixed.py search "machine learning" --limit 5
# Add a new note with auto-tagging
python mcp_cli_fixed.py add-note ./my_note.md --auto-tag
# Export search results as PDF
python mcp_cli_fixed.py export-search "PCA" --format pdf
# View weekly statistics
python mcp_cli_fixed.py stats --period week
# Start MCP server for Copilot integration
python mcp_cli_fixed.py server
# Ask questions about your notes
python mcp_cli_fixed.py qa "Explain PCA from my notes"
# Generate new notes
python mcp_cli_fixed.py generate-note "Web development best practices"
# Generate with reference
python mcp_cli_fixed.py generate-note "Advanced ML" --base-note ml_notes.md
# Search with export functionality
python mcp_cli_fixed.py search "cloud computing" --export results.json --format json
# List notes in JSON format (fixed datetime serialization)
python mcp_cli_fixed.py list-notes --format json
# Rebuild index with custom settings
python mcp_cli_fixed.py rebuild-index --chunk-size 300 --overlap 100
# Start server with custom configuration
python mcp_cli_fixed.py server --host 0.0.0.0 --port 8080
Search through your markdown notes using semantic search with advanced options.
python mcp_cli_fixed.py search [OPTIONS] QUERY
Options:
--format {text,json,table}: Output format (default: text)--limit INTEGER: Maximum number of results (default: 10)--threshold FLOAT: Minimum relevance threshold (default: 0.0)--export PATH: Export results to JSON fileExamples:
# Basic search
python mcp_cli_fixed.py search "machine learning"
# Search with JSON output
python mcp_cli_fixed.py search "python data science" --format json --limit 5
# Search with table format and threshold
python mcp_cli_fixed.py search "algorithms" --format table --threshold 0.8
# Search and export results (NEW!)
python mcp_cli_fixed.py search "cloud computing" --export search_results.json --format json
Add a new markdown note to your collection with advanced tagging options.
python mcp_cli_fixed.py add-note [OPTIONS] FILE
Options:
--auto-tag: Automatically generate tags for the note--rebuild: Rebuild search index after adding noteExamples:
# Add note without tags
python mcp_cli_fixed.py add-note ./my_note.md
# Add note with auto-tagging
python mcp_cli_fixed.py add-note ./research.md --auto-tag
# Add note and rebuild index
python mcp_cli_fixed.py add-note ./new_findings.md --auto-tag --rebuild
Export search results in various formats with custom output paths.
python mcp_cli_fixed.py export-search [OPTIONS] QUERY
Options:
--format {pdf,html,markdown,json}: Export format (default: pdf)--output PATH: Output file path--limit INTEGER: Maximum results to export (default: 20)Examples:
# Export as PDF
python mcp_cli_fixed.py export-search "machine learning" --format pdf
# Export as HTML with custom output
python mcp_cli_fixed.py export-search "web development" --format html --output web_guide.html
# Export as Markdown
python mcp_cli_fixed.py export-search "docker" --format markdown --output docker_guide.md
# Export as JSON with limit
python mcp_cli_fixed.py export-search "python" --format json --limit 15 --output python_topics.json
View comprehensive system statistics with multiple time periods.
python mcp_cli_fixed.py stats [OPTIONS]
Options:
--period {day,week,month,all}: Time period for statistics (default: week)--format {text,json}: Output format (default: text)Examples:
# Weekly statistics
python mcp_cli_fixed.py stats --period week
# Monthly statistics in JSON
python mcp_cli_fixed.py stats --period month --format json
# Daily statistics
python mcp_cli_fixed.py stats --period day
# All-time statistics
python mcp_cli_fixed.py stats --period all
List all available notes with metadata and sorting options.
python mcp_cli_fixed.py list-notes [OPTIONS]
Options:
--sort {name,modified,size}: Sort order (default: name)--format {text,json}: Output format (default: text)Examples:
# List notes sorted by name
python mcp_cli_fixed.py list-notes
# List notes sorted by modification date
python mcp_cli_fixed.py list-notes --sort modified
# List notes sorted by size
python mcp_cli_fixed.py list-notes --sort size
# List notes in JSON format (FIXED: datetime serialization)
python mcp_cli_fixed.py list-notes --format json
Rebuild the search index with advanced configuration options.
python mcp_cli_fixed.py rebuild-index [OPTIONS] [NOTES_ROOT]
Options:
--model TEXT: Embedding model to use--chunk-size INTEGER: Text chunk size--overlap INTEGER: Chunk overlap size--force: Force rebuild even if files unchangedExamples:
# Basic rebuild
python mcp_cli_fixed.py rebuild-index
# Rebuild with different model
python mcp_cli_fixed.py rebuild-index --model all-mpnet-base-v2
# Rebuild with custom chunk settings (FIXED!)
python mcp_cli_fixed.py rebuild-index --chunk-size 300 --overlap 100
# Force rebuild
python mcp_cli_fixed.py rebuild-index --force
# Rebuild specific directory
python mcp_cli_fixed.py rebuild-index ./my_notes
Start the MCP server for Copilot integration with improved error handling.
python mcp_cli_fixed.py server [OPTIONS]
Options:
--host TEXT: Server host (default: 127.0.0.1)--port INTEGER: Server port (default: 8181)--no-admin: Disable admin HTTP interfaceExamples:
# Start server with defaults
python mcp_cli_fixed.py server
# Start server on custom port
python mcp_cli_fixed.py server --port 8080
# Start server on custom host
python mcp_cli_fixed.py server --host 0.0.0.0
# Start server without admin interface
python mcp_cli_fixed.py server --no-admin
# Start server with custom host and port
python mcp_cli_fixed.py server --host 0.0.0.0 --port 9090
Ask questions about your notes using AI-powered question answering.
python mcp_cli_fixed.py qa [OPTIONS] QUESTION
Options:
--limit INTEGER: Maximum context chunks (default: 5)--model TEXT: AI model to use (default: gemini-1.5-pro)Examples:
# Ask a question
python mcp_cli_fixed.py qa "Explain PCA from my notes"
# Ask with more context
python mcp_cli_fixed.py qa "What are machine learning algorithms?" --limit 10
Generate new notes based on prompts using AI.
python mcp_cli_fixed.py generate-note [OPTIONS] PROMPT
Options:
--base-note PATH: Use existing note as reference--output PATH: Custom output filename--model TEXT: AI model to use (default: gemini-1.5-pro)Examples:
# Generate a note
python mcp_cli_fixed.py generate-note "Web development best practices"
# Generate with reference
python mcp_cli_fixed.py generate-note "Advanced PCA" --base-note pca_notes.md
# Custom output
python mcp_cli_fixed.py generate-note "ML algorithms" --output ml_guide.md
Customize the behavior using environment variables:
# Set embedding model
set MCP_MODEL_NAME=all-mpnet-base-v2
# Set chunk size for text processing
set MCP_CHUNK_SIZE=200
# Set chunk overlap
set MCP_OVERLAP=50
# Set environment
set MCP_ENVIRONMENT=production
The system uses config.py for advanced configuration. You can modify:
The CLI includes multiple fallback systems for maximum reliability:
# 1. Setup and check system
python mcp_cli_fixed.py list-notes
python mcp_cli_fixed.py stats
# 2. Add new research notes
echo "# Machine Learning Research
Recent advances in neural networks and deep learning" > research.md
python mcp_cli_fixed.py add-note ./research.md --auto-tag --rebuild
# 3. Search and analyze
python mcp_cli_fixed.py search "neural networks" --format table --limit 5
# 4. Export findings
python mcp_cli_fixed.py export-search "deep learning" --format pdf --output ml_research.pdf
# 5. View statistics
python mcp_cli_fixed.py stats --period week --format json
# 6. Start server for Copilot
python mcp_cli_fixed.py server
# Add multiple notes
for file in ./new_notes/*.md; do
python mcp_cli_fixed.py add-note "$file" --auto-tag
done
# Rebuild index after batch
python mcp_cli_fixed.py rebuild-index
# Export multiple searches
python mcp_cli_fixed.py export-search "machine learning" --format pdf --output ml.pdf
python mcp_cli_fixed.py export-search "web development" --format html --output web.html
python mcp_cli_fixed.py export-search "docker" --format markdown --output docker.md
# High-precision search
python mcp_cli_fixed.py search "machine learning algorithms" --threshold 0.8 --limit 10
# Export search with custom filename
python mcp_cli_fixed.py search "data science" --export ds_results.json --format json
# Search with table output
python mcp_cli_fixed.py search "python libraries" --format table --limit 8
# Set custom model
set MCP_MODEL_NAME=all-mpnet-base-v2
set MCP_CHUNK_SIZE=300
set MCP_OVERLAP=100
# Test with new settings
python mcp_cli_fixed.py rebuild-index
python mcp_cli_fixed.py search "machine learning" --limit 5
1. Import Errors:
# Check dependencies
pip install -r requirements.txt
# Verify Python path
python -c "import sys; print(sys.path)"
2. Search Not Working:
# Rebuild index
python mcp_cli_fixed.py rebuild-index
# Check if notes directory exists
dir notes\*.md
3. JSON Serialization Errors (FIXED!):
# This now works automatically
python mcp_cli_fixed.py list-notes --format json
4. Export Functionality (NEW!):
# Export search results
python mcp_cli_fixed.py search "query" --export results.json --format json
5. Server Not Starting:
# Check port availability
netstat -an | findstr :8181
# Try different port
python mcp_cli_fixed.py server --port 8080
6. Rebuild Index Issues (FIXED!):
# Now supports all arguments
python mcp_cli_fixed.py rebuild-index --chunk-size 300 --overlap 100
Enable debug output for troubleshooting:
# Run with verbose output
python mcp_cli_fixed.py search "test" --limit 3
Run comprehensive tests to verify all functionality:
# Run all diagnostic tests
python debug_cli.py
python quick_fix.py
python test_cli_simple.py
python test_cli_fixes.py
python test_all_fixes.py
python final_test.py
# Test CLI help
python mcp_cli_fixed.py --help
# Test basic functionality
python mcp_cli_fixed.py list-notes
python mcp_cli_fixed.py stats
# Test search
python mcp_cli_fixed.py search "test" --limit 3
# Test export
python mcp_cli_fixed.py search "test" --export test.json --format json
# Test without MCP server (uses fallback)
python mcp_cli_fixed.py search "test" --limit 3
# Test with missing dependencies (graceful degradation)
python mcp_cli_fixed.py export-search "test" --format pdf
git checkout -b feature-namepython -m pytestgit commit -am 'Add new feature'git push origin feature-name# Clone repository
git clone https://github.com/your-repo/markdown-notes-mcp.git
cd markdown-notes-mcp
# Create development environment
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt
pip install -r requirements-dev.txt
# Run tests
python -m pytest
# Run linting
flake8 mcp_cli_fixed.py
black mcp_cli_fixed.py
This project is licensed under the MIT License - see the LICENSE file for details.
For support and questions:
Happy note-taking with AI-powered search! 🚀📝
Last updated: September 2025
A semantic search system for Markdown notes with Model Context Protocol (MCP) server integration. Build searchable embeddings indexes from your Markdown files and expose them via JSON-RPC 2.0 over std
Visão geral
A semantic search system for Markdown notes with Model Context Protocol (MCP) server integration. Build searchable embeddings indexes from your Markdown files and expose them via JSON-RPC 2.0 over stdio for LLM integrations.
Ferramentas
Ainda não há lista de ferramentas. Servidores remotos recebem uma após a primeira verificação de saúde.
Perguntas frequentes
Copie nesta página a configuração stdio para Cursor, Claude Desktop, Claude Code ou VS Code. Ela usa a instalação do publicador, não um proxy do PlugMCP.
Este registro não lista nenhuma variável de ambiente obrigatória.
Markdown Notes roda localmente via stdio.
Última verificação: 2026-10-28. A semantic search system for Markdown notes with Model Context Protocol (MCP) server integration. Build searchable embeddings indexes from your Markdown files and expose them via JSON-RPC 2.0 over stdio for LLM integrations.