mcp-local-memory
Local RAG MCP server for code editors: store and query documents in a vector DB (ChromaDB + Ollama embeddings), then answer questions with retrieval-augmented generation via a local LLM (Ollama).
Features
- store_document — Store text with a title; long content is chunked automatically.
- query_documents — Semantic search with optional metadata filters and distance threshold.
- ask_rag — Retrieve relevant chunks and generate an answer using only that context (Ollama).
- list_documents / delete_document — Inspect and remove stored items.
- export_documents / import_documents / import_from_file — Export stored chunks (ID, text, metadata) as JSON and import them into another setup (either by passing JSON or reading from a local file).
All embeddings and (optionally) generation run locally via Ollama; no data leaves your machine.
Requirements
- Python 3.10+
- Ollama running with
nomic-embed-text(embeddings) and a chat model (e.g.llama3)
Setup```bash
python -m venv venv
source venv/bin/activate # or venv\Scripts\activate on Windows
pip install -r requirements.txt
Optional: copy `.env.example` to `.env` and set:
- `OLLAMA_HOST` (default: `http://localhost:11434`)
- `OLLAMA_MODEL` (default: `llama3`)
- `CHROMA_PERSIST_DIR` (default: `./chroma_db`)
- `COLLECTION_NAME` (default: `mcp_docs`)
- `EMBEDDING_MODEL` (default: `nomic-embed-text`); for a custom DB backend, `VECTOR_DB_PROVIDER` (dotted path to your class)
## Run as MCP server (stdio)```bash
python server.py
Using Docker with Cursor
Docker gives you a single, reproducible environment and avoids venv/path issues (e.g. Cursor using the wrong Python). Cursor talks to the MCP server over stdio by starting the container itself.
1. Prerequisites
- Docker installed and running.
- Ollama running on your host with
nomic-embed-textand a chat model (e.g.llama3).
2. Build the image
From the project root:```bash
docker build -t mcp-local-memory .
If you see **"driver not connecting"**, use the legacy builder: `DOCKER_BUILDKIT=0 docker build -t mcp-local-memory .`
**Use in this project first:** This repo’s `.cursor/mcp.json` is already set to run `mcp-local-memory:latest` with ChromaDB data in `./chroma_db` (project directory). After building the image, restart Cursor and open this project; the MCP server will use the container.
**Configurable when running the container:** Pass env with `-e` in the Docker `args`. Defaults: `OLLAMA_HOST`, `OLLAMA_MODEL` (chat, default `llama3`), `EMBEDDING_MODEL` (embeddings, default `nomic-embed-text`), `CHROMA_PERSIST_DIR`, `COLLECTION_NAME`. Use whatever embedding model your Ollama instance supports (e.g. `nomic-embed-text`, `mxbai-embed-large`).
#### 3. Add the server to Cursor (other projects or global)
Add an MCP server entry so Cursor starts the container and uses it for tools.
**Where to put the config**
- **This project only:** create or edit `.cursor/mcp.json` in this repo.
- **All projects:** edit your user MCP config:
- **Linux:** `~/.cursor/mcp.json` or `~/.config/cursor/mcp-config.json`
- **macOS:** `~/.cursor/mcp-config.json`
- **Windows:** `%APPDATA%\Cursor\mcp-config.json`
**Config (Linux)**
Add this inside the existing `"mcpServers"` object (or create it):```json
"local-rag-memory": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"--add-host=host.docker.internal:host-gateway",
"-e", "OLLAMA_HOST=http://host.docker.internal:11434",
"-v", "/absolute/path/to/local-rag-data:/app/chroma_db",
"mcp-local-memory"
],
"env": {}
}
Replace /absolute/path/to/local-rag-data with any path where you want ChromaDB data to persist on your machine. To use a different Ollama embedding model, add e.g. "-e", "EMBEDDING_MODEL=your-model" to args (default is nomic-embed-text). Same for OLLAMA_MODEL (chat model for ask_rag, default llama3).
Config (macOS / Windows with Docker Desktop)
Use the same structure but omit the "--add-host=host.docker.internal:host-gateway" entry from args (Docker Desktop already resolves host.docker.internal):json
"local-rag-memory": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"-e", "OLLAMA_HOST=http://host.docker.internal:11434",
"-v", "/path/on/your/machine/local-rag-data:/app/chroma_db",
"mcp-local-memory"
],
"env": {}
}
On Windows use a path like C:\Users\You\.cursor\local-rag-data; on macOS use e.g. $HOME/.cursor/local-rag-data (expand it to a full path in the JSON).
4. Restart Cursor
Restart Cursor (or Developer: Reload Window) so it picks up the new MCP server.
5. Verify
In Cursor chat, ask: “What MCP tools do you have?” You should see store_document, query_documents, ask_rag, list_documents, and delete_document. You can then say e.g. “Store a note titled Test with content Hello” and “Query for Test” to confirm the server and Ollama are working.
To export data for use in another setup, call export_documents in Cursor chat (optionally with a metadata_filter JSON string). Copy the JSON and import it into another instance by replaying store_document calls, calling import_documents(documents_json=...), or writing a small script that iterates over the exported list and calls db.store_document for each entry. For environments that can't pass arguments, save the JSON to rag_import.json (or the path set in IMPORT_PATH) and call the no-arg import_from_file MCP tool to ingest it.
Troubleshooting
- “driver not connecting” when running
docker build: The Docker daemon isn’t responding. Restart Docker Desktop (or runsudo service docker startif using the engine in WSL). Ensure WSL integration is enabled in Docker Desktop → Settings → Resources → WSL Integration. Trydocker context use defaultand run the build again. - “No such file or directory” / container exits: Ensure the image was built:
docker build -t mcp-local-memory . - Ollama errors in tools: Ollama must be running on the host; the container reaches it at
http://host.docker.internal:11434. On Linux, the--add-host=host.docker.internal:host-gatewayarg is required. - Data not persisting: The
-vpath must be a directory on your host; create it if needed (e.g.mkdir -p ~/.cursor/local-rag-data).
For non-Docker Cursor setup (venv, UI), see RAG_ANALYSIS.md.
Custom implementations and seeds
The app is built so you can plug in your own data and, if you want, your own backend.
Same config everywhere
All settings and the DB are centralized in config.py (and .env). The MCP server and any script you add use the same store if they use the same env:
OLLAMA_HOST,OLLAMA_MODEL,CHROMA_PERSIST_DIR,COLLECTION_NAME,EMBEDDING_MODEL
So custom scripts and the server stay in sync without hardcoding paths or collection names.
Custom seed scripts
You can add your own seed scripts (e.g. my_seed_script.py) that write into the same RAG store the MCP server uses:
- Use the shared config and DB:```python
import uuid
import config
db = config.get_db()
```
-
Call
store_documentwith your own(title, content)pairs and optionalmetadata(e.g. project, type). -
Run from the project root (so
configanddbresolve):bash ./venv/bin/python my_seed_script.py
Define your own list of (title, content) pairs (and optional metadata), then call db.store_document for each. To keep data separate (e.g. one collection per project), set COLLECTION_NAME (and optionally CHROMA_PERSIST_DIR) in .env or in the environment before running your seed or the server.
Custom VectorDB backend
If you want to use a different store (e.g. another vector DB), you can plug it in without changing the MCP server:
-
Implement the
VectorDBinterface fromdb.vector_db:store_document,query_documents,list_documents,delete_documentwith the same signatures. -
Point config at your class via env:
bash VECTOR_DB_PROVIDER=my_package.my_db.MyProvider
Your class will be instantiated with:collection_name,persist_directory,ollama_base_url,embedding_model(same asChromaProvider). If your backend needs different args, wrap it in a thin adapter that accepts these and maps them. -
Run the server (or seeds) as usual; they will use
config.get_db()and thus your provider.
This way the MCP server stays the same and users can connect their own implementation freely.
License
MIT
Security
See SECURITY.md for a privacy/sanitization checklist before committing or releasing.
