markdown-rag-mcp by SowmeshSharma0 - MCP Server

Markdown RAG MCP Server

A Model Context Protocol (MCP) server that provides RAG (Retrieval-Augmented Generation) capabilities for markdown documents. This server uses Qdrant for vector storage, Ollama for embeddings, and integrates seamlessly with Cursor IDE.

📚 Additional MCP Resources:

- Learn how to connect to Atlassian (Jira, Confluence) through MCP

🎥 Find the demos here:

Brown Bag Session 1 - Onboarding RAG Demos

Features

📄 Ingest and index markdown documents
🔍 Semantic search using vector embeddings
🤖 Ollama-powered embeddings (nomic-embed-text)
💾 Qdrant vector database for efficient retrieval
🔌 MCP protocol integration with Cursor IDE
🐳 Docker-based setup for easy deployment

Prerequisites (Fresh Laptop Setup)

1. Install Homebrew (macOS Package Manager)

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

After installation, follow the on-screen instructions to add Homebrew to your PATH.

2. Install pnpm and node as given in the repo: https://github.com/Sixt/com.sixt.web.public/edit/master/README.md

3. Install Rancher Desktop

Download Rancher Desktop for Mac from (intel or silicon - M series chips): https://rancherdesktop.io/
Install the application
Open Rancher Desktop
In Rancher Desktop Preferences:
- Select Container Runtime: dockerd (moby) (for Docker API compatibility)
- Apply the settings and wait for Rancher to restart
Verify Docker is running:

docker --version
docker-compose --version

5. Install Git (if not already installed)

brew install git

6. Install Cursor IDE

Download Cursor from: https://cursor.com/download
Install the application
Open Cursor

Project Setup

1. Clone or Download the Project

cd ~/Desktop/Workspace
# If using git:
git clone <your-repo-url> markdown-rag-mcp
cd markdown-rag-mcp

# Or if you already have the folder, just navigate to it:
cd markdown-rag-mcp

2. Install Project Dependencies

pnpm install

This will install all required packages including:

@modelcontextprotocol/sdk - MCP SDK
@qdrant/js-client-rest - Qdrant client
ollama - Ollama client
express - HTTP server
And other dependencies

3. Start Docker Services

pnpm run docker:up

pnpm run docker:reset

This command will:

Start Qdrant vector database (on ports 6333, 6334)
Start Ollama embedding service (on port 11434)

⏳ Wait 1-2 minutes for services to initialize.

4. Setup Ollama Model

After Docker services are running, pull and setup the embedding model:

pnpm run docker:setup-model

This will download the nomic-embed-text model (2GB). This step is required after:

First time setup
Running pnpm run docker:reset
Running pnpm run docker:up on a fresh environment

💡 ProTip: Disable Cato VPN or any corporate VPN before running this command. Dont worry abt the error at the end.

5. Verify Docker Services are Running

# Check Qdrant is running
pnpm run docker:check-qdrant

# Check Ollama is running
pnpm run docker:check-ollama

# View logs if needed
pnpm run docker:logs

6. Build the TypeScript Project

pnpm run build

This compiles the TypeScript code to JavaScript in the dist/ folder.

7. Ingest Sample Documents - on which you want to ask questions

If you have markdown files to ingest:

pnpm run ingest add <pathName> <repoName>

Example:

# Ingest a single markdown file
pnpm run ingest add ./sampleInputs/web_README.md com.sixt.web.public

# Or with a relative path
pnpm run ingest add path/to/your/document.md com.sixt.web.public

To delete a document:

pnpm run ingest delete <filename>

Connect MCP Server to Cursor

1. Locate Cursor's MCP Configuration File

Use Cursor's settings:

Open Cursor
Press Cmd + Shift + P (Command Palette)
Type "Preferences: Open User Settings (JSON)"
Look for MCP configuration section

2. Add MCP Server Configuration

Add this configuration to your mcp.json file (create it if it doesn't exist):

{
  "mcpServers": {
    "markdown-rag": {
      "url": "http://localhost:3000/mcp"
    }
  }
}

Note: This configuration assumes:

The MCP server is running on port 3000 (default)
Docker services (Qdrant and Ollama) are already running

3. Start the MCP Server

Before connecting Cursor, make sure to start the MCP server:

# Make sure Docker services are running first
pnpm run docker:up
pnpm run docker:setup-model

# Build and start the MCP server
pnpm run build
pnpm start

The server will run at http://localhost:3000/mcp and must be kept running while using Cursor.

4. Verify MCP Connection

In Cursor, you should now have access to the MCP tools. You can verify by:

Opening the Cursor chat/AI panel
The markdown-rag server should appear in the available MCP servers list
You should have access to tools like:
- ingest_markdown: Ingest markdown documents
- search: Search through ingested documents
- list_documents: List all ingested documents
- delete_document: Delete specific documents

⚠️ Important Tips

Port Configuration: Only change default ports (3000, 6333, 11434) if necessary. If you do, update both docker-compose.yml and mcp.json.
Disable VPN: Turn off Cato VPN or corporate VPN when downloading models or starting Docker services for the first time.
Verify Containers First: Always check containers are running before using MCP: docker ps
Use Absolute Paths: In mcp.json, use full paths like /Users/you/path/to/dist/index.js, not relative paths.
Rebuild After Changes: Run pnpm run build after code changes. If you modify docker-compose.yml, restart containers with pnpm run docker:restart. Then restart Cursor completely (Cmd+Q).
Be Patient on First Setup: Initial setup takes 3-5 minutes to download images and models. Don't interrupt.
Manually remove containers in case of issues: If pnpm docker:down / pnpm docker:reset doesnt work as intended goto rancher, stop and delete the containers manually.

Using the MCP Server

Ingest Markdown Documents

You can ingest markdown files through Cursor's AI chat using the MCP tools, or via command line:

pnpm run ingest

The server will:

Parse markdown files
Split them into semantic chunks
Generate embeddings using Ollama
Store them in Qdrant vector database

Search Documents

Use Cursor's AI chat to search through your documents. The MCP server will:

Convert your query to embeddings using Ollama
Search the Qdrant vector database
Return relevant document chunks with metadata

Example Usage in Cursor

You: "Search for documentation about API authentication"

The MCP server will retrieve relevant chunks from your ingested markdown documents.

Available Commands

Docker Management

# Start services
pnpm run docker:up

# Stop services
pnpm run docker:down

# View all logs
pnpm run docker:logs

# View Qdrant logs only
pnpm run docker:logs:qdrant

# View Ollama logs only
pnpm run docker:logs:ollama

# Restart services
pnpm run docker:restart

# Check Ollama models
pnpm run docker:list-models

# Setup Ollama model manually
pnpm run docker:setup-model

# Complete reset (removes all data)
pnpm run docker:clean

# Clean and restart
pnpm run docker:reset

Development

# Install dependencies
pnpm install

# Build TypeScript
pnpm run build

# Start MCP server
pnpm start

# Build and start
pnpm run dev

# Ingest documents
pnpm run ingest

# Run tests
pnpm test

Project Structure

markdown-rag-mcp/
├── src/
│   ├── index.ts           # MCP server entry point
│   ├── server.ts          # MCP server implementation
│   ├── ingest.ts          # Document ingestion logic
│   ├── constants.ts       # Configuration constants
│   └── services/
│       ├── embeddings.ts  # Ollama embedding service
│       └── qdrant.ts      # Qdrant vector store service
├── dist/                  # Compiled JavaScript output
├── sampleInputs/          # Sample markdown files
├── qdrant_data/           # Qdrant database storage
├── ollama_data/           # Ollama models storage
├── docker-compose.yml     # Docker services configuration
├── tsconfig.json          # TypeScript configuration
├── package.json           # Node.js dependencies
└── README.md             # This file

Configuration

Environment Variables

The following environment variables can be configured:

Variable	Default	Description
`PORT`	`3000`	MCP server port
`QDRANT_URL`	`http://localhost:6333`	Qdrant database URL
`OLLAMA_URL`	`http://localhost:11434`	Ollama service URL

Constants (src/constants.ts)

COLLECTION_NAME: Qdrant collection name (markdown_docs)
EMBEDDING_DIMENSIONS: Vector dimensions (768 for nomic-embed-text)
DEFAULT_CHUNK_SIZE: Document chunk size (1000 characters)
DEFAULT_SEARCH_LIMIT: Number of search results (5)
DEFAULT_EMBEDDING_MODEL: Ollama model (nomic-embed-text)

Troubleshooting

Docker containers won't start

# Check Docker Desktop is running
docker ps

# Check logs for errors
pnpm run docker:logs

# Try resetting
pnpm run docker:down
pnpm run docker:up

Ollama model not available

# Manually pull the model
pnpm run docker:setup-model

# Check if model is loaded
pnpm run docker:list-models

# Check Ollama logs
pnpm run docker:logs:ollama

MCP server not connecting in Cursor

Verify the server builds successfully: pnpm run build
Check the path in mcp.json is correct (use absolute path)
Ensure Docker services are running: pnpm run docker:up
Check server logs for errors
Restart Cursor completely (Cmd + Q, then reopen)

System Requirements

OS: macOS (Linux/Windows with minor adjustments)
RAM: 8GB minimum (16GB recommended for better performance)
Disk Space: 5GB for Docker images and models
Node.js: v18 or higher
Docker: Latest version
Internet: Required for initial model download

Architecture

Components

MCP Server (src/server.ts)
- Implements Model Context Protocol
- Exposes tools for document management and search
- Runs as HTTP server for Cursor integration
Embedding Service (src/services/embeddings.ts)
- Interfaces with Ollama
- Generates 768-dimensional embeddings using nomic-embed-text
Vector Store (src/services/qdrant.ts)
- Manages Qdrant vector database
- Handles document storage and retrieval
- Performs semantic similarity search
Ingestion Pipeline (src/ingest.ts)
- Parses markdown documents
- Chunks text for optimal retrieval
- Generates and stores embeddings

Data Flow

Markdown Files
    ↓
Ingestion Pipeline
    ↓
Text Chunking
    ↓
Ollama Embeddings (nomic-embed-text)
    ↓
Qdrant Vector Store
    ↓
MCP Server ←→ Cursor IDE
    ↓
Semantic Search Results

MCP Tools

The server exposes the following MCP tools:

`ingest add`

Ingest markdown documents into the vector database.

Parameters:

content (string): Markdown content to ingest
metadata (object): Optional metadata (title, source, etc.)

`search_knowledge`

Search through ingested documents using semantic similarity.

Parameters:

query (string): Search query
limit (number, optional): Number of results (default: 5)

Returns: Array of relevant document chunks with scores and metadata

`ingest delete`

Delete a specific document from the vector database.

Parameters:

documentId (string): ID of the document to delete

Contributing

Contributions are welcome! Please follow these guidelines:

Fork the repository
Create a feature branch
Make your changes
Test thoroughly
Submit a pull request

License

ISC License

Support

For issues, questions, or contributions:

Create an issue in the repository
Check existing documentation
Review troubleshooting section

Next Steps

✅ Complete the setup steps above
📄 Add your markdown documents to a folder
🔧 Use the MCP ingest_markdown tool through Cursor to index your documents
💬 Ask questions about your documents through Cursor's AI chat
🚀 The RAG system will retrieve relevant context from your documents

Happy coding! 🎉