NoteSentry — Assistente MCP para Notas Clínicas MIMIC-III
swiftruru/notesentry-mcp
MIMIC-III assistant local com aprovação humana, múltiplos MCP servers e auditoria completa
Ver no GitHubAssistente desktop local-first para explorar notas clínicas MIMIC-III com LLM Ollama, servidores MCP especializados (consultas, suporte clínico, segurança farmacêutica, FHIR) e aprovação humana em loop. Toda a inferência, dados e auditoria permanecem no dispositivo com governança total.
Instalação
npx convez-ai swiftruru/notesentry-mcp1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Exploração e análise de notas clínicas com privacidade garantida
- Suporte clínico estruturado com formulários SOAP e triagem
- Verificação de segurança farmacêutica e interações medicamentosas
- Pipeline de grounding, raciocínio e revisão humana obrigatória
Veredito

Projeto sofisticado que implementa corretamente HITL (human-in-the-loop) como barreira impermeável — todo tool call requer aprovação explícita. Arquitetura modular com 4 MCP servers nativos é exemplar para governança clínica. Restrição a macOS e dependência de MIMIC-III (dados credenciados) limitam o alcance, mas a solução é genuinamente valiosa para pesquisadores e clínicos que precisam de privacidade absoluta.
README
A tradução para o português deste README ainda está na fila.
NoteSentry
Local‑first MIMIC‑III clinical‑notes assistant — explore clinical notes with a local LLM, MCP tools, and human‑in‑the‑loop approval. All data and inference stay on‑device.
English · 繁體中文
NoteSentry is a desktop assistant for exploring MIMIC‑III clinical notes in natural language. A local Ollama LLM queries a local SQLite database through MCP tools and turns the results into an answer.
Beyond free‑form chat it ships structured clinical apps (a Triage and a SOAP‑note form), a modular multi‑MCP backend (notes query · clinical support · pharmacy safety · FHIR vitals), and a grounding → reasoning → human‑review pipeline where every tool call is approved by you. All four MCP servers are bundled; the architecture is additive — a new server is pure addition and HITL, audit, routing, and the agent loop apply automatically.
Data stays on this device. This data is governed by the PhysioNet Credentialed Data Use Agreement (DUA) and may not leave the machine: all inference runs on local Ollama; every tool call requires your explicit approval (HITL); nothing is uploaded, no telemetry, and all app data (config, logs, conversations) is stored locally on your machine.
Screenshots
Captured from the running app via the bundled Playwright capture harness (npm run capture). More in the system‑analysis document.
Download
📖 New here? Follow the Installation & First‑Run Guide — it walks you from a fresh machine to a working app (Ollama, Python, database, settings).
Prebuilt installers for macOS / Windows / Linux are attached to every release. The buttons below always download the latest version:
macOS button = Apple Silicon .dmg · Windows = installer · Linux = AppImage · other variants below
| Platform | Direct download (always latest) |
|---|---|
| macOS · Apple Silicon | .dmg · .zip |
| macOS · Intel | .dmg · .zip |
| Windows · x64 | installer .exe · portable .exe |
| Linux · x64 | .AppImage · .deb |
The app itself ships with the MCP server scripts bundled. You still need Ollama and Python 3 (
pip install "mcp[cli]") installed, plus amimic_notes.dbyou build from your own credentialed MIMIC‑III data — see Prerequisites. On macOS the build is ad‑hoc signed (no paid Apple certificate), so on first launch use right‑click → Open.
Chat experience
A Claude‑Chat‑like desktop experience:
- Multi‑conversation management: create, switch, rename, search, delete; conversations
are saved to
conversations/in the project folder (clinical text never leaves the machine) and persist across restarts. - Auto‑titling: after the first exchange, a local Ollama model generates a short title (still editable).
- Live streaming: token‑by‑token responses; stop generation anytime.
- Markdown & code: headings, lists, tables, bold, links render correctly; code blocks get syntax highlighting and one‑click copy.
- Message actions: copy a whole reply; regenerate the last reply.
- Markdown export: save a conversation as
.md(native Save As — choose any location, defaults to Documents and remembers the last folder; includes tool calls and results, fully local). - Follow‑up suggestions: clickable next‑question prompts are generated on a new chat, after each turn, and when loading an old conversation.
- Bilingual (i18n): one‑click
繁體中文 / Englishtoggle in the top‑right — the UI, the model's answer language, auto‑titles, suggestions, export labels, and error messages all switch; the choice is remembered inconfig.json. - Activity‑rail layout: the left icon rail switches
Chat / Apps / Tools / Audit / Settings / About.
Adding a language (no component changes)
Translation files live in src/shared/locales/<lang>/<namespace>.json (both the renderer and
the main process auto‑load them via import.meta.glob). To add a third language (e.g.
Japanese), just add a src/shared/locales/ja/ folder of JSON files — the top‑right toggle
picks it up automatically, with no changes to any component code. Each locale's
common.json provides language.self / language.short for the toggle's display name.
Productivity & UX
- System health bar: a header indicator (Ollama / model / MCP / database / Python) that auto‑checks on startup and after saving settings. Click it for per‑item status with actionable hints, a re‑check, and a jump to Settings; a startup banner surfaces the top problem so failures are never silent.
- Dark mode: a header theme toggle (system / light / dark), remembered across launches and following the OS in system mode.
- Command palette (
⌘K/Ctrl+K): search every command — new chat, switch views, export, reconnect MCP, re‑check health, theme, language — plus a jump‑to‑conversation section. - Keyboard shortcuts:
⌘Nnew chat ·⌘1–5switch views ·⌘,settings ·⌘Eexport ·Escstops generation / closes the palette. - HITL approval dialog:
Enterapproves,Escrejects, focus is trapped, and tool arguments are pretty‑printed. - Audit tools: search + filter (all / approved / rejected / errors), expand a row for the full
arguments, result summary and session id, and export the log as
.jsonl. - Global toasts (saved / exported / reconnected / deleted), smart auto‑scroll with a "scroll to latest" button, and retry on error bubbles.
- Window memory & collapsible sidebar: the window remembers its size/position; the conversation list collapses to widen the chat — toggle in the chat header, or click the active Chat rail icon.
- Demo starter prompts: a new chat offers one‑click sample questions that each exercise a real tool (triage vitals, SOAP drafting, data queries, and a deliberately‑missing record).
- Accessibility: keyboard‑visible focus on every control, accessible names on icon buttons and
inputs,
<html lang>synced to the UI language, a screen‑reader status region for streaming (instead of reading every token), a combobox/listbox command palette, keyboard‑operable conversation rows, semantic landmarks, WCAG‑AA dark contrast, andprefers-reduced-motion.
Clinical apps
The Apps tab turns free‑form chat into four structured, form‑driven workflows — one per MCP pillar. Each form builds a grounded prompt and runs it through the same agent loop — so every tool call still asks for your approval, and the result lands in a normal chat thread you can keep working in.
- App A · Triage: enter the chief complaint and vital signs; the LLM calls
assess_vital_signs(rule‑based red‑flag check) andget_ttas_reference, then suggests a TTAS level with its reasoning. The triage nurse makes the final call. - App B · SOAP note: enter exam keywords and a note type; the LLM expands them into a
SOAP draft grounded by
get_soap_template. The physician reviews and signs off. - App C · Medication safety: enter the current medication list and known allergies; the
LLM calls
check_drug_interactionsandcheck_allergy_conflict, then summarizes the risk level and recommendations. The physician and pharmacist confirm. - App D · Vital signs → FHIR: enter vital signs; the LLM calls
vitals_to_fhirto emit HL7 FHIR R4Observationresources (LOINC codes, UCUM units) — demonstrating standards‑based exchange across systems.
No more blank forms. Each form has two one‑click ways to populate it:
- Load sample: built‑in, realistic presets — instant and demo‑safe. Clicking again cycles to the next case.
- ✨ AI‑generate sample: the local Ollama model generates a random synthetic case as JSON and fills the form (~6–15 s). If generation fails it automatically falls back to a built‑in preset (with a toast), so a live demo never stalls.
Samples are synthetic (no PHI) and only fill the fields — nothing is submitted until you press the form's action button, and each resulting tool call is still individually approved.
Architecture
- Main process (
src/main): holds every "touches data / network" capability — launching and monitoring the Python MCP subprocesses, listing/calling MCP tools, calling local Ollama (streaming), running the agent loop, HITL approval, writing the audit log, reading/writing settings. - Preload (
src/preload): exposes a whitelistedwindow.apiviacontextBridge. - Renderer (
src/renderer): pure React / Tailwind UI withcontextIsolationon,nodeIntegrationoff,sandboxon; talks to main only throughwindow.api.
Data flow: Composer → chat:send → agentLoop → Ollama stream; if the model returns
tool_calls, approvalBroker raises an approval request → the renderer shows
ApprovalDialog → only after you approve does mcpClient.callTool run → the result is fed
back → the loop continues until the final answer. Every tool call (including rejections) is
written to the audit log.
Prerequisites
-
Ollama:
ollama serverunning, with a tool‑calling model ready (recommendedgpt-oss:20b; orollama pull qwen2.5. See "Model recommendation" below). -
Python + MCP:
python3with the MCP package:pip install "mcp[cli]" -
Build the database: use the bundled
mcp/scripts/build_db.pyto importNOTEEVENTS.csvinto SQLite (standard library only — handles multi‑GB files, no pandas needed).# Full import (~2M rows; a few minutes depending on machine) python3 mcp/scripts/build_db.py --csv MIMIC-III/dataset/NOTEEVENTS.csv --db mimic_notes.db # Import and build the full-text index (for search_notes; a few extra minutes) python3 mcp/scripts/build_db.py --csv MIMIC-III/dataset/NOTEEVENTS.csv --db mimic_notes.db --with-fts # Or add the full-text index to an existing database (no re-import) python3 mcp/scripts/build_db.py --db mimic_notes.db --fts-only # Quick test with a small slice (first 20k rows) python3 mcp/scripts/build_db.py --db mimic_notes_test.db --limit 20000 --rebuild
The project bundles four MCP servers (FastMCP / stdio) and
mcp/scripts/build_db.py. The app connects to all of them at once (a multi‑MCP architecture) and routes each tool to the right server by name. Onlymcp/servers/mimic_mcp_server.pyneeds the database; the other three are self‑contained knowledge/rule servers that work out of the box.
MCP servers & tools (four servers, all read‑only / side‑effect‑free)
mcp/servers/mimic_mcp_server.py — MIMIC notes query (needs mimic_notes.db)
| Tool | Purpose |
|---|---|
list_note_categories | Per‑category (CATEGORY) note counts |
count_notes | Count by category / patient / DESCRIPTION keyword |
get_patient_overview | Record summary for one patient (SUBJECT_ID) |
search_notes | Full‑text search of note text (TEXT), returns matched snippets (needs the FTS index) |
get_note_text | Full text of a single note by ROW_ID |
mcp/servers/clinical_support_mcp_server.py — clinical support (no database needed)
| Tool | Purpose | App |
|---|---|---|
assess_vital_signs | Rule‑based vital‑sign assessment with red‑flag alerts (zero hallucination, reproducible) | A · triage |
get_ttas_reference | TTAS 5‑level triage criteria + chief‑complaint red flags (built‑in knowledge) | A · triage |
get_soap_template | SOAP note structure and section‑by‑section guidance | B · charting |
mcp/servers/pharmacy_support_mcp_server.py — pharmacy safety (no database needed)
| Tool | Purpose |
|---|---|
check_drug_interactions | Pairwise interaction check over a drug list, with severity (major / moderate / minor) and rationale |
check_allergy_conflict | Cross‑checks prescribed drugs against the patient's allergies, including drug‑class matches (e.g. penicillin → amoxicillin) |
get_drug_reference | Built‑in reference for a drug (class, common cautions) |
mcp/servers/nis_fhir_mcp_server.py — nursing / vitals as FHIR (no database needed)
| Tool | Purpose |
|---|---|
vitals_to_fhir | Converts vital signs into a FHIR R4 Bundle of Observation resources (LOINC codes, UCUM units) |
get_fhir_reference | Field mapping for common FHIR resources (Patient / Observation / AllergyIntolerance / MedicationStatement) |
Design principle: triage levels and SOAP drafting are produced by LLM reasoning; these tools only ground that reasoning in deterministic references (rule‑based vitals, the official triage scale, a fixed format) — the final decision is always reviewed by a clinician. This is the "MCP grounding → LLM reasoning → human review" three‑layer defense.
MCP server integration contract
The app launches an MCP server as:
<pythonPath> <mcpScriptPath> # e.g. python3 ./mcp/servers/mimic_mcp_server.py
and passes the absolute SQLite path via the MIMIC_DB_PATH environment variable. Make
sure mcp/servers/mimic_mcp_server.py reads it to locate the database, e.g.:
import os
DB_PATH = os.environ.get("MIMIC_DB_PATH", "mimic_notes.db")
If your server obtains the DB path another way (hard‑coded or CLI argument), align it to read
MIMIC_DB_PATH, or point the script path in Settings at a launcher that already embeds the
correct path.
Develop & run
npm install
npm run dev # development (HMR)
npm run build # produce out/
npm start # preview the built app
npm run typecheck
npm run package # build a distributable app (electron-builder)
Note: if your shell sets
ELECTRON_RUN_AS_NODE=1(some Electron‑based tools do), Electron runs as plain Node instead of a GUI. Run in a clean terminal, or useenv -u ELECTRON_RUN_AS_NODE npm start.
App icon & name (macOS)
- The icon lives at
build/icon.png(packaging) andresources/icon.png(runtime); electron-builder generates the.icnswhen packaging. - On macOS in
npm run dev, the Dock name, the bold menu‑bar title, and the About panel icon are read from the runningElectron.appbundle —app.setName()cannot change them. This project uses scripts/patch-dev-name.mjs to automatically patch the Electron bundle'sCFBundleNameand icon to NoteSentry before eachnpm run dev(viapredev), so the name and icon are correct in dev too. If macOS caches the old values, fully quit Electron and runnpm run devagain. - The packaged
.appusesproductName/build.icon, so its name and icon are always correct.
Settings
Settings are stored in config.json at the project root (created on first launch) and can
also be edited in the app's "Settings" tab:
| Field | Default | Notes |
|---|---|---|
ollamaUrl | http://localhost:11434 | Local addresses only (hard guard) |
model | gpt-oss:20b | Must support tool calling (see below) |
pythonPath | python3 | Python used to launch all MCP servers |
dbPath | ./mimic_notes.db | SQLite path, passed to each server via MIMIC_DB_PATH |
language | zh-TW | UI and model‑answer language (also via the top‑right toggle) |
mcpServers[] | mimic + clinical + pharmacy + nis | Multiple MCP servers (id / name / scriptPath / enabled); missing defaults are auto‑merged into an existing config.json on launch |
Model recommendation (tool‑call reliability)
Whether HITL reliably triggers depends on whether the model emits a structured tool call rather than describing one in prose. Measured (same question, same hardened prompt):
gpt-oss:20b(recommended, default): native function calling, reliably emits structured tool calls, and fastest (~25s to the first tool call). Already installed, no download.qwen2.5: lightweight (7B), reliable tool calling, good for lower‑end machines (ollama pull qwen2.5).qwen3.6:27b: works, but reasoning‑oriented and slower; occasionally writes the tool call as prose (then HITL won't trigger).
The agent loop uses
temperature: 0.3and injects the available tool list into the system prompt (forbidding invented tables and prose tool calls), which greatly reduces fabrication and missed HITL prompts (see agentLoop.ts).
Audit log
Every tool call (time, tool name, parameters, approved/rejected, result summary/error) is:
- shown live in the "Audit" tab;
- appended to
logs/audit-YYYY-MM-DD.jsonl(one entry per line, never leaves the project folder).
Security
- Connects only to local Ollama; an
ollamaUrlthat isn't localhost / 127.0.0.1 is blocked. - The renderer CSP allows only
'self'and local Ollama; external links and navigation are disabled. - Every tool call requires human approval — there is no "allow all" bypass.
config.json,logs/,conversations/,exports/, the database, and the MIMIC dataset are all in.gitignore; files containing clinical text are never committed.
Tech stack
Electron · React · TypeScript · Tailwind CSS · zustand · react-i18next ·
Model Context Protocol (@modelcontextprotocol/sdk) · Ollama · SQLite (FTS5) · FastMCP (Python) ·
FHIR R4 (LOINC / UCUM)
License & acknowledgments
- Author: YU‑RU, PAN (潘昱如) · Data Decision Analysis Laboratory · Department of Information Management, National Taipei University of Nursing and Health Sciences
- Data source: MIMIC‑III Clinical Database (PhysioNet). Use of this data is subject to the PhysioNet Credentialed Data Use Agreement (DUA); the dataset and any derived files containing clinical text must not be shared or committed.
- License: MIT (code).