mainframe-mcpCAUTION
100% local knowledge and persistent memory for coding agents. GPU-accelerated hybrid search with source citations and a low VRAM footprint, powered by one shared MCP daemon.
Overview
From the repository's own README, as read at the audited commit. Badges and raw HTML are left out.
Local knowledge for coding agents. Carry useful context across conversations.
Mainframe makes your project's Markdown searchable across conversations. It finds relevant passages in documentation, research, and project instructions, returns source citations, and saves session notes for later recall. One local daemon serves your MCP clients and terminal, sharing a single model stack.
Quick start · Connect your agent · For agents · Configuration and operations
Why Mainframe
- Find knowledge across projects. Combine semantic and keyword search, then rerank passages for your question.
- Follow the evidence. Results identify the source file and section, with verified line citations when the file still matches.
- Carry decisions forward. Save an immutable session note and include it in future searches when you need that history.
- Share the models. Opening another client does not load another set of weights.
Your Markdown files remain the source of truth. The search index is a rebuildable cache. Retrieval runs locally; your calling agent decides how to use the evidence.
Quick start
You need Python 3.10+, Git for installation, and an NVIDIA GPU with BF16 support for the default models. See models and hardware for measured memory use.
1. Install
Use a dedicated Python environment with CUDA-enabled PyTorch. This example uses CUDA 12.8; choose a build supported by your system:
python -m pip install torch --index-url https://download.pytorch.org/whl/cu128 python -m pip install "git+https://github.com/sushiHex/mainframe-mcp.git@main"
Create a Python environment first
python -m venv .venv
Activate it with .venv\Scripts\Activate.ps1 in PowerShell, or source .venv/bin/activate on Linux. Then run the installation commands abov
c730dec0094aOBSERVED · 2026-10-12Connect
Built from this server's own package name, version and transport as found in its source — not copied from anyone's documentation, so it cannot drift against a page we do not control.
claude mcp add mainframe-mcp -- uvx mainframe-mcp
{
"mcpServers": {
"mainframe-mcp": {
"command": "uvx",
"args": [
"mainframe-mcp"
]
}
}
}Exposed tools (6)
5 read · 0 write · 1 destructive. Blast radius: 1 tool can delete or overwrite — an agent that can be talked into calling a tool can be talked into calling this one.
| Tool | Risk | Description |
|---|---|---|
delete_file | destructive | Delete a file and its chunks from the Mainframe index. |
ingest_file | read | Ingest a markdown file into the Mainframe. Chunks, embeds, deduplicates, and indexes. |
ingest_projects | read | DEPRECATED — prefer sync_index (a superset that also prunes deleted files). Scan all ~/repos/*/research/*.md and ~/repos/*/CLAUDE.md files and ingest new or changed ones. |
list_files | read | List all files in the Mainframe with ingestion status and retrieval counts. |
reload_config | read | Hot-reload the config file (MAINFRAME_CONFIG env, else ~/.claude/mainframe/config.json) for live-read knobs (chunker, search pool/fetch/recency, tiers). Model changes (embedder/reranker/nli/consolidator/contextual) are NOT applied — they are returned as restart_required_for. |
status | read | return await asyncio.to_thread(app.status) |
Trust audit
CAUTIONgrade C · trust 77/100 Install with care. The audit found things worth knowing before you trust its output.
| Layer | What it checks | Result |
|---|---|---|
| L0 | Provenance & inventory | PASS |
| L1 | Static analysis of the code | WARN |
| L2 | Instruction surface (what it tells the agent) | PASS |
| L3 | Class-specific surface | WARN |
| L4 | Behavioural (sandbox) | SKIPPED |
What the source does
- Filesystem
- declared (4 observation(s))
- Network
- declared (8 observation(s))
- Shell
- none-observed
- Dependencies
- pinned
- Secrets in source
- none-found
Findings (19)
self.base_url = f"http://127.0.0.1:{self.info['port']}" if self.info else Nonestate["base"] = f"http://127.0.0.1:{info['port']}/mcp"client = httpx.Client(base_url=f"http://127.0.0.1:{info['port']}",delete_file
.gitleaks.toml
.gitleaksignore
module = importlib.import_module(module_name)
module = importlib.import_module(module_name)
module = importlib.import_module(module_name)
module = importlib.import_module(module_name)
module = importlib.import_module(module_name)
# The GPU eval (eval/evaluate.py --min-score) runs manually/nightly on the 3090,
doc_id = hashlib.md5(str(md_file).encode()).hexdigest()[:12]
doc_id = hashlib.md5(file_path.encode()).hexdigest()[:12]
h = int(hashlib.md5(tok.encode("utf-8")).hexdigest(), 16)h = int(hashlib.md5(tok.encode("utf-8")).hexdigest(), 16)session_id="../../zz")
**HTTP clients** can connect to `http://127.0.0.1:7433/mcp` using Streamable HTTP. Use `/mcp/ro` for search and status only. See [client setup](docs/V2.md#connect-clients) for configuration and authen
Register `http://127.0.0.1:7433/mcp` as a Streamable HTTP MCP server, using the
Gates applied: no_behavioural_pass.
c730dec0094afull audit observations/trust-audit/mcp-server/sushihex__mainframe-mcp.json · Report an issue / request a re-scanAudit history
Every audit this server has had. A grade with a past is a grade somebody is still checking.
| Date | Source | Verdict | Grade | Score | Change |
|---|---|---|---|---|---|
| 2026-10-12 | c730dec0094a | CAUTION | C | 77 | first audit |
Questions
What is the mainframe-mcp MCP server?
100% local knowledge and persistent memory for coding agents. GPU-accelerated hybrid search with source citations and a low VRAM footprint, powered by one shared MCP daemon.
What tools does mainframe-mcp expose?
6 in total: 5 read-only, 0 that write, and 1 that can delete or overwrite (delete_file). Every one is listed on this page with its risk.
Is mainframe-mcp safe to connect to an agent?
With care. The audit graded it C (77/100) and found 19 things worth knowing before you trust this server, listed below with the exact line each was found on. Separately from the audit: 1 of its tools can destroy data, so scope the token you give it to what you actually need.
What credentials does mainframe-mcp need?
No credential environment variables were found in its source, so it appears to need none.
How does mainframe-mcp run?
It speaks stdio and streamable-http, so it runs as a local process your client starts. It is published on PyPI as mainframe-mcp.
How current is this page?
The grade is for one exact copy of the source (c730dec0094a), read on 2026-10-12. The repository is watched and re-audited when it changes.