AI LocalBase MCP
A self-hosted RAG app with a web interface and a built-in MCP server: documents, Qdrant and answers with sources.
- 386 ★ on the repository
- Last commit
- MIT
Extended access
Why this level
- Through MCP an agent reads the base's documents and, with wider key scopes, uploads files and deletes data.
- Without `ENABLE_AUTH=true` a service on a server has no login, and MCP must not be opened in that state.
Install
- Works in
Manual install
docker compose up --buildCopy `.env.example` to `.env` before running. Then enable `ENABLE_MCP=true` and create an API key.
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- Through MCP an agent reads the base's documents and, with wider key scopes, uploads files and deletes data.
- Without `ENABLE_AUTH=true` a service on a server has no login, and MCP must not be opened in that state.
This is third-party code. Review the repository files before installing.
What it does
AI LocalBase is a standalone knowledge-base application with a web interface: Go and Gin on the backend, React on the frontend, Qdrant as the vector database. An agent connects to it through the built-in MCP server over HTTP and JSON-RPC and gets access to documents, search and chat. It loads TXT, Markdown, text PDF, xlsx and csv: files are split into chunks, embedded and searched with reranking and de-duplicated selection. MCP is off by default and turns on with `ENABLE_MCP=true`. Tools are split into read, write and dangerous ones, and access is set by an API key with `mcp:*` scopes: `mcp:read`, `mcp:upload`, `mcp:eval` and `mcp:danger` for deletion. There are tools for answers with sources, knowledge-base quality checks, search-mode comparison and evaluation-set creation, and large imports run as background jobs with cancellation.
Who it is for. People who want to give an agent access to their own document base on their own server, without cloud RAG services.
Good fit when
- Team documents sit in PDFs, Markdown and spreadsheets and an agent must answer from them with a source link.
- The knowledge base lives on your own server and Cursor or Claude Desktop connect to it over MCP.
- Search quality is tested: modes are compared and evaluation sets are built from your own documents.
- A large batch of files is indexed in the background while you follow the job.
Not a fit when
- Deployment across several servers: the app is built as a single instance, and a second copy would break writes to SQLite.
- A cloud service with no self-hosting: you would need Docker Compose, Qdrant and a model.
- Open access without login: MCP should be enabled only with `ENABLE_AUTH=true`.
Example request
Find the payment clauses of the contract in the AI LocalBase knowledge base and cite the sources.MCP
- Transport
- http
- Authentication
- API key
Environment variables
ENABLE_MCPrequired- Turns the MCP server on, `false` by default.
ENABLE_AUTHrequired- Turns on login and API keys, and MCP should not be opened without it.
MCP_BASE_PATH- MCP path, `/mcp` by default.
Limitations
The app needs Docker Compose, Qdrant and models for chat and embeddings: Ollama or any OpenAI-compatible API. It is built for a single instance: chat history in SQLite and MCP jobs in memory cannot be shared between replicas. `QDRANT_VECTOR_SIZE` must match the embedding model, and a model change needs a new `QDRANT_COLLECTION_PREFIX`. The MCP server returns JSON, issues no session IDs and does not support SSE. The README is written in Chinese.
How to disable. Set `ENABLE_MCP=false`, restart the backend and revoke the API key in the app settings. `docker compose down` stops all services.
FAQ
How do I bring up AI LocalBase?
Copy `.env.example` to `.env` and run `docker compose up --build`. The interface opens at `http://localhost:4173`, and chat and embedding models are set on the settings page.
How do I connect it to Cursor or Claude Desktop?
Enable `ENABLE_MCP=true`, create an API key with `mcp:*` scopes and set `http://127.0.0.1:8080/mcp` as an HTTP MCP server. The app settings include ready templates for Cherry Studio, Claude Desktop and Cursor.
Which scopes should the key get?
`mcp:read` is enough for reading, uploads need `mcp:upload`, evaluation needs `mcp:eval`. The `mcp:danger` scope opens deletion tools, so grant it only when necessary.
Which files can I upload?
TXT, Markdown, PDF with a text layer, xlsx and csv.
Can I run several copies?
No. The app is built for a single instance, and `docker compose scale backend=2` is not supported.
Discussion
No questions or reviews yet.
Related
MCP serversA local MCP server that turns a folder of documents into a knowledge base with hybrid search for Claude Code and Cursor
The official Graphlit MCP server: an agent collects material from Slack, GitHub, mail and websites into a knowledge base and searches it
A local knowledge base over PDFs, scans and Office files: hybrid search, access control and answers that cite the page
A CLI and MCP server that extracts structured knowledge from documents: graphs, hypergraphs, and fact search with sources
On-premises RAG in containers with an MCP server: the agent searches your documents while data stays local
MCP server for the Flexible GraphRAG platform: ingest from 14 data sources, hybrid search and AI answers over a knowledge graph
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Authentication | Repository stars | Main difference |
|---|---|---|---|---|
| AI LocalBase (this card) | no | API key | 386 | |
| knowledge-rag | no | not required | 301 | a local MCP server over a folder of documents, while AI LocalBase is a full app with a web interface, Qdrant and key scopes |
| Pharos | no | API key | 241 | a local knowledge base for PDFs, scans and Office files, while AI LocalBase adds search-quality evaluation and background import jobs |
README in short
The repository describes a Docker Compose app for personal knowledge bases and small teams. Detailed commands and variables are in `docs/getting-started.md`, and MCP tools, scopes and call examples in `docs/mcp.md`.