mcp-ratchet-clinical-charting
This MCP server lets Claude perform clinical charting tasks for home health: search patients, document visits, and review visit history, with a complete mock backend and read-only FHIR support.
Search for patients by name, ID, or phone, with optional status filtering and result limits.
Create visit notes with visit details, vitals, SOAP-style documentation, interventions, education, patient response, and next-visit planning.
Retrieve patient visit history with optional date-range and visit-type filters.
Use fictional mock data safely; mock notes are stored in memory as unsigned
pending_reviewrecords.In FHIR mode, search patients and read history only;
create_visit_noteis refused, and it is not for real patient data.
With the mock backend and DASHBOARD_SYNC=on, copies newly created visit notes to a Supabase-backed demo EMR dashboard using SUPABASE_URL and SUPABASE_ANON_KEY, so documented visits appear in an external dashboard (synthetic data only).
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mcp-ratchet-clinical-charting Search for patient Eleanor Thompson"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
chartinghero
MCP server for clinical charting with Claude. Lets Claude search patients, document home health visits (SOAP note, vitals, interventions, education) and read visit history.
Status: the mock backend is complete. The FHIR R4 (US Core) backend can search patients and read visit history; it cannot write yet. See docs/FHIR-PIVOT-PLAN.md. Do not use with real patient data.
Status
Component | Status |
MCP server (stdio) | Working, mock backend |
Unit tests |
|
FHIR R4 backend, read ( | Working against a local or sandbox FHIR R4 server |
FHIR R4 backend, write ( | Not in this build; the call is refused |
Production EMR writes | Out of scope until SMART user auth (0.3.0) |
Related MCP server: Medical Knowledge MCP Server
Quick start
From npm
The 0.1.0 npm release was published under an earlier package name, which will be deprecated. Until chartinghero is published, install from source.
From source
git clone https://github.com/m2ai-mcp-servers/chartinghero.git
cd chartinghero
npm install
npm run build
npm testMock mode
Mock mode is the default backend. It:
uses 5 fictional test patients
stores visit notes in memory (lost on restart)
saves new notes as
pending_review, unsigned, authored by a fictional nurseprefixes every tool result with
[MOCK DATA: fictional patients]
FHIR mode (read only)
With BACKEND=fhir the server reads from a FHIR R4 server:
At startup it reads
/metadataand stops unlessfhirVersionstarts with4.0.search_patientlooks up thePT-xxxxxidentifier, the server id, the name (every word must match; add aYYYY-MM-DDdate of birth to narrow it) and the phone number when the server supports phone search. A phone number matches as the server stores it; the digits-only spelling is tried as well.get_patient_historylists home health Encounters newest first. A visit with an unsigned note ispending_review, and so is one whose status the server reports as unknown; with a signed note it iscompleted. A visit with no note takes the Encounter's own status, and a cancelled visit stays cancelled. Encounters entered in error are left out. Vitals count when they are linked to the visit or were taken during it.When the server cannot return notes and vitals with the Encounters, history is built from the nurse notes instead: one row per visit, with no visit type.
Results come one page at a time; a result with more pages includes a
cursorto pass back. A cursor keeps the filters and page size it was issued with. A total shown as3+counts only the pages read so far. The order across pages is the server's (_sort=-date).create_visit_noteis refused. WithFHIR_WRITE=onit still resolves the patient and runs the duplicate-visit search, then stops. A note-only write (no Encounter) is refused outright until it has a duplicate check of its own.A bearer token is only sent over https, or over http to a loopback address.
The server only trusts what it can check: it filters results again itself, follows paging links only under FHIR_BASE_URL, refuses redirects, and reports upstream errors by HTTP status and issue code only.
Local FHIR server
docker compose -f docker/compose.fhir.yml up -d # HAPI FHIR R4 on 127.0.0.1:8080, data in memory
node scripts/seed-fhir.mjs # fictional patients, visits, vitals and notes (waits for the server to come up)Then run with BACKEND=fhir FHIR_BASE_URL=http://127.0.0.1:8080/fhir FHIR_ENVIRONMENT=local FHIR_PRACTITIONER_ID=<Practitioner id> VISIT_TIMEZONE=America/New_York. Restarting the container wipes its data.
Tools
Tool | Description |
| Find a patient by name, ID, or phone |
| Document a visit with vitals and a SOAP note |
| List a patient's previous visits |
Example usage (in Claude)
"Search for patient Eleanor Thompson"
→ Returns patient PT-10001 with demographics and status
"Create a visit note for PT-10001 with blood pressure 120/80"
→ Creates and stores the visit note with vitals
"Get visit history for PT-10001"
→ Returns the list of previous visitsClaude Desktop
Add to the Claude Desktop config file:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"chartinghero": {
"command": "node",
"args": ["/absolute/path/to/chartinghero/dist/index.js"]
}
}
}Restart Claude Desktop, then check that search_patient, create_visit_note and get_patient_history are listed. Try: "Search for patient Eleanor".
Test patients (mock mode)
ID | Name | Status | Primary diagnosis |
PT-10001 | Eleanor Thompson | Active | Type 2 Diabetes, CHF |
PT-10002 | Robert Martinez | Active | COPD, Post-surgical |
PT-10003 | Margaret Wilson | Active | Parkinson's Disease |
PT-10004 | James Thompson | Active | Post-stroke rehab |
PT-10005 | Dorothy Anderson | Discharged | Hip replacement |
Configuration
Config fails closed: an invalid value stops the server at startup with a message naming the variable.
Variable | Required | Description |
| When any |
|
| When | FHIR server, |
| No |
|
| No |
|
| No |
|
| No |
|
Variables from the 0.1.0 release are still read for one release with a deprecation warning, but no longer select a backend.
Project structure
chartinghero/
├── src/
│ ├── index.ts # MCP server entry point
│ ├── config.ts # Fail-closed configuration
│ ├── config/hosts.ts # WRITE_HOSTS allowlist
│ ├── legacy-env.ts # Deprecated 0.1.0 env vars (one release)
│ ├── backends/ # PatientBackend seam, mock backend, factory, signed paging cursors
│ ├── backends/fhir/ # FHIR client, /metadata capabilities, read path, write pre-flight
│ ├── auth/ # none, static bearer token
│ ├── mappers/ # DTO mappers
│ ├── tools/ # search-patient, create-visit-note, get-patient-history
│ ├── services/ # patient-service (validation + projection hook), mock-data, supabase-service
│ ├── types/ # Patient and visit types
│ └── utils/ # Logger, errors
├── tests/ # service, config, startup, backends/ (in-memory FHIR server), contract/ (both backends)
├── docker/compose.fhir.yml # local FHIR R4 server
├── scripts/seed-fhir.mjs # fictional seed data for it
├── docs/
│ └── FHIR-PIVOT-PLAN.md # Backend pivot plan
├── package.json
├── tsconfig.json
└── jest.config.jsDevelopment
npm run dev # run with tsx
npm test # jest
npm run lint # eslintnpx jest tests/contract runs one contract against both backends. The FHIR side replays recorded responses by default. To run it against the local server, seed it and set FHIR_IT_BASE_URL=http://127.0.0.1:8080/fhir; add FHIR_RECORD=1 to rewrite the recordings in tests/fixtures/recorded/.
Related projects
chartinghero-demo-emr: demo EMR dashboard that displays visits written by this server.
License
MIT
Available Tools
3 toolscreate_visit_noteA
Create a visit note for a patient in the PointCare EMR system.
This tool documents a home health visit including vital signs, assessment, and care plan. Use search_patient first to get the patient ID.
Required fields: patientId, visitType, visitDate, timeIn, timeOut Recommended fields: vitalSigns, subjective, objective, assessment, plan
Inputs: patientId (required), visitType (required), visitDate (required), timeIn (required), +11 more.
get_patient_historyA
Retrieve visit history for a patient from the PointCare EMR system.
Returns a list of previous visits with dates, types, and key information. Use this to review patient history before creating a new visit note.
Use search_patient first to get the patient ID.
Inputs: patientId (required), limit, startDate, endDate, +1 more.
search_patientA
Search for a patient in the PointCare EMR system by name, ID, or phone number.
Returns matching patient records with basic information. Use this tool to find patients before creating visit notes or retrieving history.
Examples:
Search by name: "Eleanor Thompson"
Search by ID: "PT-10001"
Search by phone: "555-0101"
Inputs: query (required), searchType, status, limit.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 3 tools
Each tool has a distinct, non-overlapping purpose: searching for patients, retrieving visit history, and creating new visit notes. No ambiguity exists between them.
All tools follow a consistent verb_noun pattern (search_patient, get_patient_history, create_visit_note) using snake_case, making it predictable and easy to understand.
With only 3 tools, it is on the lower end but still appropriate for a focused clinical charting server. They cover the core workflow of searching, reviewing history, and creating notes without unnecessary bloat.
The tool set covers essential operations (search, history, create) but lacks update and delete functionalities for visit notes, which are notable gaps for a complete CRUD lifecycle in clinical charting.
Maintenance
Related MCP Connectors
Telehealth support for Claude, Codex and Cursor: investigate cases and connect your tools.
MCP server unifying ERPs, CRMs, APIs and knowledge base for Claude, ChatGPT and Gemini.
Hosted Apple Health MCP for Claude and ChatGPT, works outside the US. iPhone app, no local server.
Hosted MCP server exposing US hospital procedure cost data to AI assistants
Related MCP Servers
- AlicenseNot gradedqualityNot gradedmaintenanceA production-grade MCP server that enables AI assistants to securely manage healthcare data through clinical tools for patient vitals, lab results, and medication ordering. It prioritizes security and compliance with features like HIPAA-ready audit logging, PII redaction, and role-based access control.-
- AlicenseAqualityDmaintenanceMCP server for connecting Claude Desktop to a local medical knowledge base with real-time file watching, enabling natural language interaction with medical documents.9MIT
- AlicenseAqualityDmaintenanceA Claude-compatible MCP server that exposes health-domain tools over 100% synthetic data, built with security and compliance in mind.4MIT
- FlicenseNot gradedqualityAmaintenanceEnables LLM-based agents and MCP-compatible clients such as Claude Desktop to perform full CRUD operations on Fast Healthcare Interoperability Resources and query clinical data through natural-language prompts. It also provides document ingestion with semantic search, a RAG-ready retrieval pipeline, and LOINC terminology lookup and validation.-