home / mcp / markdown rag mcp server
Exposes a model-context protocol MCP server for semantic search over markdown docs with rate limiting and vector storage.
Configuration
View docs{
"mcpServers": {
"ashrobertsdragon-rag-mcp": {
"command": "uv",
"args": [
"run",
"--directory",
"/absolute/path/to/markdown-rag",
"markdown-rag",
"/absolute/path/to/docs",
"--command",
"mcp"
],
"env": {
"OLLAMA_HOST": "http://localhost:11434",
"POSTGRES_DB": "embeddings",
"GOOGLE_MODEL": "models/gemini-embedding-001",
"OLLAMA_MODEL": "mxbai-embed-large",
"POSTGRES_HOST": "localhost",
"POSTGRES_PORT": "5432",
"POSTGRES_USER": "postgres",
"DISABLED_TOOLS": "delete_document,update_document",
"GOOGLE_API_KEY": "your_api_key",
"POSTGRES_PASSWORD": "your_password",
"RATE_LIMIT_REQUESTS_PER_DAY": "1000",
"RATE_LIMIT_REQUESTS_PER_MINUTE": "100"
}
}
}
}You run a compact MCP server that exposes a query-capable endpoint for an AI assistant to retrieve and reason over Markdown documentation. It combines semantic search, chunked markdown handling, rate-limited embeddings, and PostgreSQL-backed vector storage, giving you reliable, self-contained access to your docs through a simple client interface.
You interact with the server via an MCP client. Start the MCP server using the same directory where you keep your Markdown docs, and then connect your client (for example Claude Desktop or another MCP client) to the running server. The server exposes a set of tools that let you search, list, update, or refresh the document index, so you can quickly retrieve relevant sections and ask questions based on your documentation.
Prerequisites include a modern Python runtime and a PostgreSQL database with the pgvector extension enabled. You also need an MCP-compatible client to connect to the server.
Step 1: Prepare your environment - Install Python 3.11 or newer - Install PostgreSQL 12 or newer with pgvector enabled - Optionally obtain Google Gemini API credentials if you plan to use Google embeddings or set up Ollama for local embeddings - Ensure you have an MCP-compatible client installed (for example Claude Desktop or another MCP client)
You run the MCP server using a local command via the MCP client. The following configuration shows how to start the server locally with a provided directory of Markdown documents and the server command set to MCP mode.
{
"mcpServers": {
"markdown_rag": {
"type": "stdio",
"command": "uv",
"args": [
"run",
"--directory",
"/absolute/path/to/markdown-rag",
"markdown-rag",
"/absolute/path/to/docs",
"--command",
"mcp"
],
"env": {
"POSTGRES_PASSWORD": "your_password",
"GOOGLE_API_KEY": "your_api_key"
}
}
}
}Once the server is running, you can use the following tools to interact with your documents. You don’t need to know the low-level protocol; you issue high-level commands through your MCP client.
- query: perform a semantic search over ingested Markdown content. You provide a query string and optionally the number of results.
The server uses environment variables to configure access and features. Common variables include database credentials and API keys. Set these in your environment or in the startup configuration.
To disable certain tools in production, set the DISABLED_TOOLS variable with a comma-separated list of tools you want to turn off. For example: DISABLED_TOOLS=delete_document,update_document,refresh_index.
If you encounter issues starting the server, verify that PostgreSQL is running and accessible with the provided credentials. Ensure the pgvector extension is installed in the target database. Adjust rate limits as needed via environment variables to avoid hitting quotas.
Keep all secrets in environment variables or a secure secret store. Do not commit credentials to version control. Use a read-only database user for query-only deployments and rotate API keys regularly.
Semantic search over documentation via the MCP endpoint to retrieve relevant results.
List all ingested documents in the index.
Remove a document from the index by filename.
Re-ingest a specific document to refresh its content in the index.
Scan the directory and ingest new or modified files to keep the index current.