mcp-ratchet-clinical-charting

MCP server for clinical charting with Claude (codename: Ratchet) - Enables Claude to document patient visits directly into Electronic Medical Records, reducing administrative burden for home health nurses.

Note: Currently runs in Mock Mode for development/testing. Production EMR integration coming soon.

Status

Component	Status
MCP Server	✅ Working (Mock Mode)
Unit Tests	✅ 20/20 Passing
Claude Desktop	✅ Ready for Testing
PointCare API	⏳ Pending API Documentation

Current Mode: Mock Mode - Uses realistic test data for development and testing.

Quick Start

From npm (Recommended)

Terminal

npx mcp-ratchet-clinical-charting

From Source

bash

git clone https://github.com/m2ai-mcp-servers/mcp-ratchet-clinical-charting.git
cd mcp-ratchet-clinical-charting
npm install
npm run build
npm run dev  # Development mode
npm test     # Run tests

Mock Mode

Ratchet runs in mock mode by default when POINTCARE_API_URL is not configured. Mock mode:

Uses 5 fictional test patients
Stores visit notes in memory
Returns realistic responses
Perfect for development and Claude Desktop testing

Available Tools

Tool	Description	Mock Mode
`search_patient`	Find patient by name, ID, or phone	✅ Working
`create_visit_note`	Document a patient visit with vitals	✅ Working
`get_patient_history`	Retrieve patient visit history	✅ Working

Example Usage (in Claude)

Code

"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 visit note with vitals

"Get visit history for PT-10001"
→ Returns list of previous visits

Claude Desktop Integration

Configure Claude Desktop

Add to your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

config.json

{
  "mcpServers": {
    "ratchet": {
      "command": "npx",
      "args": ["-y", "mcp-ratchet-clinical-charting"]
    }
  }
}

For production mode with EMR integration:

config.json

{
  "mcpServers": {
    "ratchet": {
      "command": "npx",
      "args": ["-y", "mcp-ratchet-clinical-charting"],
      "env": {
        "POINTCARE_API_URL": "https://api.pointcare.com",
        "POINTCARE_API_KEY": "your-api-key"
      }
    }
  }
}

Step 3: Restart Claude Desktop

Restart Claude Desktop to load the new MCP server.

Step 4: Verify

In Claude Desktop, you should see:

search_patient tool available
create_visit_note tool available
get_patient_history tool available

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

Origin Story

Ratchet evolved from the M2AI NurseCall n8n workflow, built to help home health nurses with visit documentation:

Code

Current Flow (M2AI NurseCall):
┌─────────┐    ┌─────────┐    ┌─────────┐    ┌─────────┐
│ Twilio  │───>│  n8n    │───>│  VAPI   │───>│  Email  │
│  SMS    │    │ Workflow│    │  Call   │    │ Summary │
└─────────┘    └─────────┘    └─────────┘    └─────────┘

The Problem: Visit notes go to email but still need manual entry into PointCare EMR.

Ratchet's Solution:

Code

Future Flow (with Ratchet):
┌─────────┐    ┌─────────┐    ┌──────────┐    ┌───────────┐
│ Twilio  │───>│  n8n    │───>│ Ratchet  │───>│ PointCare │
│  SMS    │    │ Workflow│    │   MCP    │    │    EMR    │
└─────────┘    └─────────┘    └──────────┘    └───────────┘

Configuration

Variable	Required	Description
`POINTCARE_API_URL`	No*	PointCare API base URL
`POINTCARE_API_KEY`	No*	API key or token
`RATCHET_MOCK_MODE`	No	Force mock mode (`true`/`false`)
`LOG_LEVEL`	No	Logging level (`debug`/`info`/`warn`/`error`)

*Required for production use. Mock mode activates when not set.

Project Structure

Code

ratchet/
├── src/
│   ├── index.ts              # MCP server entry point
│   ├── config.ts             # Configuration management
│   ├── tools/                # Tool implementations
│   │   ├── search-patient.ts
│   │   ├── create-visit-note.ts
│   │   └── get-patient-history.ts
│   ├── services/             # Business logic
│   │   ├── patient-service.ts
│   │   └── mock-data.ts
│   ├── types/                # TypeScript types
│   └── utils/                # Logger, errors
├── tests/
│   └── patient-service.test.ts
├── dist/                     # Compiled output
├── prds/
│   └── RATCHET-PRD.yaml
├── docs/
│   └── API_REQUIREMENTS.md
├── package.json
├── tsconfig.json
└── jest.config.js

Development

bash

# Run in watch mode
npm run dev

# Run tests
npm test

# Run tests with coverage
npm test -- --coverage

# Lint
npm run lint

Next Steps

Acquire PointCare API documentation - See docs/API_REQUIREMENTS.md
Complete PRD - Fill in tool specifications with real API details
Implement real API calls - Replace mock responses
Integration testing - Test with PointCare sandbox

Related Projects

GRIMLOCK - Autonomous MCP Server Factory
ratchet-demo-emr - Demo EMR React app for testing

License

MIT

Built with GRIMLOCK - Autonomous MCP Server Factory