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)
npx mcp-ratchet-clinical-charting
From Source
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)
"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
{
"mcpServers": {
"ratchet": {
"command": "npx",
"args": ["-y", "mcp-ratchet-clinical-charting"]
}
}
}
For production mode with EMR integration:
{
"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_patienttool availablecreate_visit_notetool availableget_patient_historytool 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:
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:
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
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
# 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