Pharos MCP
A local knowledge base over PDFs, scans and Office files: hybrid search, access control and answers that cite the page
- 241 ★ on the repository
- Last commit
- MIT
Extended access
Why this level
- The agent reads every document visible to the chosen identity and can expand them to whole articles
- Through `/v1/ask` the retrieved chunks go to the external DeepSeek API
- Retrieved chunks are tagged as untrusted data, but document text still lands in the agent's context
Install
- Works in
Manual install
pip install -e '.[dev]'Run in the cloned repository; Python 3.10 or newer is required. Add the `gpu` extra for GPU mode.
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- The agent reads every document visible to the chosen identity and can expand them to whole articles
- Through `/v1/ask` the retrieved chunks go to the external DeepSeek API
- Retrieved chunks are tagged as untrusted data, but document text still lands in the agent's context
This is third-party code. Review the repository files before installing.
What it does
Pharos turns PDFs, scans, docx, pptx and xlsx files into a local knowledge base and answers questions over it with a link to the source page. Search is hybrid, and access rights are checked on every request: a document with no permissions is visible to nobody. The system has two exits. The `pharos serve` command starts an HTTP API where `/v1/ask` runs a closed chain: retrieval, a check that the answer rests on the source, then a DeepSeek answer with citations. The `pharos mcp` command gives an agent such as Claude Code MCP tools, and the agent decides when to search, how to rewrite the query and whether a second pass is needed. There are six tools: `retrieve`, `list_documents`, `get_document`, `get_outline`, `expand` and `retrieve_grouped`. A resident service holds the heavy resources, because embedded Qdrant admits a single client and an 8B-parameter model takes a minute or two to load. MCP stays a thin HTTP adapter and starts instantly. Without the service, `pharos mcp --direct` works over stdio and loads the GPU model itself.
Who it is for. Teams with a growing library of PDFs, scans and Office files who need cited answers and different access rights per employee.
Good fit when
- A department holds hundreds of PDFs and decks, and the question "what do we have on this topic" needs an answer with a quote and a page number
- An agent in Claude Code should search internal documents itself and decide when to pull neighbouring chunks or the whole document
- Employees have different rights, and one person must not see another's documents even through the agent
- The index is kept on your own GPU server rather than in a cloud vector database
- You want to study how production RAG is built: the repository has 12 write-ups from chunking to evaluation, in Chinese
Not a fit when
- You need a cloud service with no administration: the index is built by hand with `pharos index` and an administrator runs the service
- There are few documents and all of them are plain text files: the agent's ordinary search over a folder is enough
- You need internet access: HTTPS and public exposure are explicit non-goals, and remote access is meant to go through a tunnel
Example request
Find everything our document library says about return terms and give the source pagesMCP
- Transport
- stdio
- Authentication
- API key
Environment variables
PHAROS_URLrequired- Address of the `pharos serve` service, `http://127.0.0.1:8787` by default
PHAROS_API_KEYrequired, secret- The identity key issued by `pharos keys new`
PHAROS_TENANT- Tenant for `--direct` mode: without it retrieval returns an empty result
DEEPSEEK_API_KEYsecret- Needed by the service for `/v1/ask`
Limitations
All documentation except the README is written in Chinese, including the series of RAG write-ups. The embedding model runs on a GPU: the sample configuration targets WSL, and Claude Code starts the server through `wsl`. The corpus for indexing comes from a directory of MinerU parse output, so scans and Office files go through that parsing first. The service and `pharos mcp --direct` cannot open the same index at once: embedded Qdrant admits a single client.
How to disable. Remove the `rag` block from the project's `.mcp.json` and the agent stops seeing the tools. If you ran the service under systemd, `sudo systemctl stop pharos` stops it. The index lives in `~/rag_real` by default.
FAQ
How do I connect Pharos to Claude Code?
Copy `.mcp.json.example` to `.mcp.json`, put in your own `PHAROS_API_KEY` and local paths and start the service. The agent gets a search tool for the library.
How do I give an employee access?
An administrator creates an identity with `python -m pharos keys new alice --tenant demo --admin`, or without `--admin` and with groups via `--principals`. The key is printed once, and the key list is kept in the file named by `PHAROS_KEYS_FILE`.
Why is a DeepSeek key needed?
It is only for `/v1/ask`, where DeepSeek writes the answer. The MCP tools do not use a DeepSeek key: the agent writes the answer from the retrieved chunks.
Can the agent widen its own rights?
No, identity is decided server-side: the key sets the tenant and groups, and tool parameters cannot change them. An unknown or missing key returns 401.
How do I run the tests without a GPU?
`python -m pytest tests -q --ignore=tests/engine` runs only the product layer on a fake retriever and MockLLM, with no GPU and no network.
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
A self-hosted RAG app with a web interface and a built-in MCP server: documents, Qdrant and answers with sources.
A CLI and MCP server that extracts structured knowledge from documents: graphs, hypergraphs, and fact search with sources
An MCP server gives agents search and answers over local documents using hybrid retrieval, reranking and section links.
An MCP server for searching and downloading academic papers from arXiv, PubMed, bioRxiv, Semantic Scholar and other open sources
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 |
|---|---|---|---|---|
| Pharos (this card) | no | API key | 241 | |
| knowledge-rag | no | not required | 301 | also hybrid search over a document folder for Claude Code, while Pharos adds per-user rights and a separate HTTP mode with cited answers |
| MCP Local RAG | no | not required | 429 | local search with no keys or external database for one person, while Pharos targets a team, a GPU service and Qdrant |
| haiku.rag | no | not required | 651 | agentic RAG with citations on embedded LanceDB, while Pharos keeps the index in Qdrant behind a service with access control |
README in short
The English README is the entry point to the system: the architecture, the HTTP and MCP doors, deployment from one box to three independent tiers, the security model and a documentation index. The author stresses that the project's decisions rest on measurements over 77 real documents.