minima

Minima is an open source RAG on-premises solution that can operate in multiple modes, including fully local Ollama-based deployment, a custom OpenAI-compatible LLM, and MCP integration for interacting with local documents. The MCP integration allows you to expose the Minima server to MCP tooling (e.g., Anthropic Desktop app) so you can query local documents through a familiar interface while the indexer runs on your machine. To start using it, you typically run the included run script or bring up the required Docker Compose setup for your chosen mode. Once running, you can access a local chat UI (if enabled) and issue queries that are answered using your local data and chosen LLM backend. The workflow supports both local-only configurations and cloud-assisted setups via a custom LLM API, depending on which mode you select.

Key capabilities include: local document indexing from a root folder (LOCAL_FILES_PATH), embedding generation for vector search, and a retrieval-augmented generation flow. If you opt for the Ollama workflow, the system uses a local Ollama model and a reranker; for a custom LLM workflow, the system communicates with your OpenAI-compatible API or other LLMS via a configured endpoint. The MCP setup via the Anthropic Desktop app allows you to send queries to Minima through a desktop UI, leveraging the local index without sending data to external servers.

To use MCP integration, ensure your environment is prepared (see the installation steps) and start the appropriate docker-compose setup for MCP. If you’re using the Claude/MCP path, you’ll typically provide the minima mcp server as shown in the example configuration and then connect via the MCP client. The Minima web UI (if enabled) is usually accessible at http://localhost:3000 or via the provided electron app in the project, allowing you to search and retrieve documents using your local data and configured LLM backend.

Prerequisites

• Docker and Docker Compose installed on your machine
• Git to clone the repository
• A local folder with documents to index (as specified by LOCAL_FILES_PATH in your .env)
• Access to an LLM backend if you plan to use a custom OpenAI-compatible API (LLM_BASE_URL, LLM_MODEL, etc.)
• For MCP usage via Anthropic Desktop app, ensure MCP is installed and configured to connect to a local minima mcp server

Installation steps

1. Clone the repository

git clone https://github.com/your-org/minima.git
cd minima

2. Prepare environment variables

• Create a .env file in the project root (or following the sample in .env.sample)
• Populate required values, e.g.:

LOCAL_FILES_PATH=/path/to/your/documents
EMBEDDING_MODEL_ID=sentence-transformers/all-mpnet-base-v2
EMBEDDING_SIZE=768
# Ollama mode (if used)
OLLAMA_MODEL=qwen2:0.5b
RERANKER_MODEL=BAAI/bge-reranker-base
# Custom LLM mode (if used)
LLM_BASE_URL=http://your-llm-address:port/v1
LLM_MODEL=Qwen/Qwen-1.7B
LLM_API_KEY=your-api-key
# MCP/ChatGPT integration (examples)
USER_ID=you@example.com
PASSWORD=your-password

3. Start in MCP mode using Docker Compose

• Fully local Ollama mode

docker compose -f docker-compose-ollama.yml --env-file .env up --build

• Custom OpenAI-compatible LLM mode

docker compose -f docker-compose-custom-llm.yml --env-file .env up --build

• ChatGPT-enabled mode

docker compose -f docker-compose-chatgpt.yml --env-file .env up --build

• MCP (Anthropic Desktop app) mode

docker compose -f docker-compose-mcp.yml --env-file .env up --build

4. If using Claude/MCP, configure the Claude app to point to the minima MCP server as shown in the README, and use the provided mcp.json snippet to ensure the MCP client connects to the local server.

5. Start the local UI for Minima (optional)

• If you’re using the standalone Electron app, navigate to the electron directory and run:

npm install
npm start

6. Verify operation

• Access the local UI (if enabled) at http://localhost:3000 and try a sample query against your LOCAL_FILES_PATH.
• For MCP, open your MCP client and connect to the minima server using the configured endpoint and credentials.

Tips and common issues:

• Ensure LOCAL_FILES_PATH contains accessible documents in supported formats (.pdf, .xls, .docx, .txt, .md, .csv).
• If you switch between Ollama and custom LLM modes, you may need to adjust LLM_BASE_URL, OLLAMA_MODEL, and RERANKER_MODEL accordingly; the Dockerfile/build may skip certain assets based on mode.
• When using MCP with Anthropic Desktop, you may need to update claude_desktop_config.json to point to the local minima MCP server as shown in the README example.
• If you encounter port conflicts, check docker-compose-*.yml files for the port mappings and update as needed.
• For performance tuning, align EMBEDDING_SIZE with the actual embedding model you’re using and ensure the vector store (e.g., Qdrant) has adequate resources.
• The environment variables USER_ID and PASSWORD are required for ChatGPT-based authentication with the local UI or MCP flows; keep credentials secure and avoid committing them to version control.