Skip to main content
Glama
mcp-ratchet-clinical-charting

mcp-ratchet-clinical-charting

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

npm test

FHIR R4 backend, read (search_patient, get_patient_history)

Working against a local or sandbox FHIR R4 server

FHIR R4 backend, write (create_visit_note)

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 test

Mock 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 nurse

  • prefixes 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 /metadata and stops unless fhirVersion starts with 4.0.

  • search_patient looks up the PT-xxxxx identifier, the server id, the name (every word must match; add a YYYY-MM-DD date 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_history lists home health Encounters newest first. A visit with an unsigned note is pending_review, and so is one whose status the server reports as unknown; with a signed note it is completed. 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 cursor to pass back. A cursor keeps the filters and page size it was issued with. A total shown as 3+ counts only the pages read so far. The order across pages is the server's (_sort=-date).

  • create_visit_note is refused. With FHIR_WRITE=on it 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

search_patient

Find a patient by name, ID, or phone

create_visit_note

Document a visit with vitals and a SOAP note

get_patient_history

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 visits

Claude 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

BACKEND

When any FHIR_* var is set

mock or fhir. Unset with no FHIR_* vars means mock, with a stderr banner.

FHIR_BASE_URL, FHIR_ENVIRONMENT, FHIR_PRACTITIONER_ID, VISIT_TIMEZONE

When BACKEND=fhir

FHIR server, local or sandbox, authoring Practitioner id, IANA time zone.

FHIR_WRITE

No

off (default) or on. on is refused unless the host is in WRITE_HOSTS (src/config/hosts.ts).

FHIR_WRITE_PROFILE, FHIR_BEARER_TOKEN, FHIR_IDENTIFIER_SYSTEM

No

full or note-only; static token; identifier namespace.

DASHBOARD_SYNC

No

off (default) or on. With on and the mock backend, new notes are copied to the demo dashboard via SUPABASE_URL and SUPABASE_ANON_KEY. Synthetic data only.

LOG_LEVEL

No

debug, info, warn or error

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.js

Development

npm run dev    # run with tsx
npm test       # jest
npm run lint   # eslint

npx 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/.

License

MIT

Available Tools

3 tools
create_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

    A3.9/5.0

    Scored across 3 tools

    Disambiguation5/5

    Each tool has a distinct, non-overlapping purpose: searching for patients, retrieving visit history, and creating new visit notes. No ambiguity exists between them.

    Naming Consistency5/5

    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.

    Tool Count4/5

    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.

    Completeness3/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      Not graded
      maintenance
      A 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.
      -
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables 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.
      -