MCP server for MedScrub PHI de-identification
npm install @medscrub/mcpModel Context Protocol (MCP) server for MedScrub PHI de-identification. Enables Claude Code, Cline, and other MCP clients to safely de-identify healthcare data during AI-assisted development.
!MedScrub in Action
MedScrub de-identifying a FHIR Patient resource in Claude Desktop - 100% accuracy on structured healthcare data
MedScrub is a HIPAA-compliant PHI (Protected Health Information) de-identification service that enables healthcare organizations to safely use AI/LLM services while maintaining patient privacy.
- Node.js: 18+ required for MCP server
- Claude Desktop: For using with Claude Code
Choose your deployment:
- Option A: Hosted API (Recommended for hackathons/demos) โจ
- Option B: Demo API with Synthea FHIR (Perfect for testing with realistic data)
- Option C: Local Docker (Full control, no external dependencies)
> ๐ก Pro Tip: Use npx to always get the latest version automatically - no manual installation or updates needed!
---
Perfect for: Testing MedScrub with realistic patient data from the Synthea FHIR MCP
See the complete guide: /DEMO.md
Quick configuration for dual MCP setup:
Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):
``json`
{
"mcpServers": {
"synthea-fhir": {
"command": "npx",
"args": ["-y", "supergateway", "--sse",
"https://synthea-mcp-1095016408887.us-central1.run.app/sse"]
},
"medscrub": {
"command": "npx",
"args": ["-y", "@medscrub/mcp"],
"env": {
"MEDSCRUB_API_URL": "https://stage.api.medscrub.dev",
"MEDSCRUB_API_KEY": "msk_test_demo0000000000000000000000000000"
}
}
}
}
> โจ Using npx: Always downloads the latest version automatically - no installation or manual updates needed!
See also: Demo Commands for 40+ copy-paste examples
---
Perfect for:
- Hackathon participants
- Quick testing and demos
- No Docker setup required
1. Visit https://medscrub.dev
2. Sign up or log in
3. Navigate to /demo page
4. Copy your JWT token (valid for 24 hours)
Add to your Claude Desktop MCP settings:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json%APPDATA%\Claude\claude_desktop_config.json
Windows: ~/.config/Claude/claude_desktop_config.json
Linux:
`json`
{
"mcpServers": {
"medscrub": {
"command": "npx",
"args": ["-y", "@medscrub/mcp"],
"env": {
"MEDSCRUB_API_URL": "https://api.medscrub.dev",
"MEDSCRUB_JWT_TOKEN": "your-jwt-token-from-website"
}
}
}
}
> โจ Using npx -y @medscrub/mcp: Always uses the latest version automatically. No installation or updates needed!
Restart Claude Desktop to load the MCP server.
Rate Limits: 100 requests per hour per user.
---
Perfect for:
- Healthcare organizations
- Production use
- Full data control (PHI never leaves your infrastructure)
`bashNavigate to proxy directory
cd ../
$3
`json
{
"mcpServers": {
"medscrub": {
"command": "npx",
"args": ["-y", "@medscrub/mcp"],
"env": {
"MEDSCRUB_API_URL": "http://localhost:3000",
"MEDSCRUB_API_KEY": "msk_test_demokey123456789012345678901234"
}
}
}
}
`> โจ Using
npx: Always uses the latest version - no installation required!$3
Restart Claude Desktop to load the MCP server.
No rate limits when running locally.
๐ง Available Tools
$3
De-identify text containing PHI.
Example:
`
User: Use medscrub__deidentify_text to scrub this clinical note:
"Patient John Doe (SSN: 123-45-6789) visited on 01/15/2023.
Email: john.doe@example.com"
`Returns:
- De-identified text with tokens
- Session ID for re-identification
- List of detected PHI entities
- Confidence scores
$3
Restore original PHI using session tokens.
Example:
`
User: Use medscrub__reidentify_text with sessionId "abc-123" to restore:
"Patient [NAME_xyz] visited on [DATE_abc]"
`$3
De-identify FHIR R4 resources with multiple output format options.
Parameters:
-
resource (required): FHIR R4 resource or Bundle to de-identify
- sessionId (optional): Existing session ID for consistency
- outputFormat (optional): Output format - see belowOutput Formats:
| Format | Description | Best For |
|--------|-------------|----------|
|
json | Full FHIR resource (default) | Production FHIR systems |
| json-compact | Minimal metadata | Smaller payloads |
| python-dict | Python dict syntax | Jupyter notebooks, copy/paste |
| llm-optimized | Human-readable text | LLM analysis |Example (Default JSON):
`
User: Use medscrub__deidentify_fhir to scrub this Patient resource:
{
"resourceType": "Patient",
"name": [{"family": "Doe", "given": ["John"]}],
"birthDate": "1980-01-15"
}
`Example (Python-Dict for Jupyter):
`
User: Use medscrub__deidentify_fhir with outputFormat="python-dict" to scrub this Patient:
{
"resourceType": "Patient",
"name": [{"family": "Smith", "given": ["John"]}],
"birthDate": "1985-03-15"
}
`Returns valid Python dict syntax that can be copy/pasted directly into Jupyter notebooks!
See Also: Format Examples Notebook
$3
Restore original PHI in FHIR resources.
$3
Get information about a de-identification session.
$3
List all PHI types that MedScrub detects (18 HIPAA Safe Harbor identifiers).
๐ Documentation Resources
The MCP server provides built-in documentation:
-
medscrub://docs/quick-start - Quick start guide
- medscrub://docs/phi-types - PHI types reference
- medscrub://docs/api-reference - API documentation
- medscrub://docs/compliance - HIPAA compliance guideAccess these in Claude Code by asking:
`
User: Read the resource medscrub://docs/quick-start
`๐ Code Examples & Tutorials
$3
Comprehensive code examples for integrating MedScrub:
- /samples/ - Multi-language samples (Python, JavaScript, TypeScript, Jupyter)
- Production-ready client libraries
- Complete examples with error handling
- Batch processing patterns
- Real-time API integration
- /jupyter-health/ - Healthcare data science with Jupyter
- 5 progressive notebooks (beginner to advanced)
- FHIR R4 coverage (all 10 resource types)
- AI-assisted analysis with MCP
- End-to-end clinical research workflow
- Synthetic sample data (HIPAA-compliant)
$3
- Jupyter Notebooks: /jupyter-health/README.md
- Python: /samples/python/README.md
- JavaScript: /samples/javascript/README.md
- TypeScript: /samples/typescript/README.md
๐ก Use Cases
$3
`
User: I have this clinical note that needs to be de-identified
before I share it with my team. Can you scrub it?[Clinical note with PHI]
`Claude Code will use
medscrub__deidentify_text automatically.$3
`
User: Generate a de-identified version of this patient data
for my test suite.[Patient data with PHI]
`$3
`
User: I need to de-identify these FHIR Patient resources
before loading them into my test environment.[FHIR Bundle with PHI]
`$3
`
User: I want to ask Claude about this clinical case,
but it contains PHI. Can you help?[Clinical case with PHI]
`Claude Code will de-identify before processing, then re-identify the response.
๐ Security & Compliance
$3
- โ
Your Machine: MedScrub Docker API runs locally
- โ
In Memory Only: Session data stored in memory, encrypted
- โ
Never External: PHI never sent to external services
- โ
Complete Control: You control when to de-identify/re-identify
$3
MedScrub implements the HIPAA Safe Harbor de-identification method (ยง164.514(b)(2)), removing all 18 identifier types:
1. Names
2. Geographic subdivisions
3. Dates (except year)
4. Phone/Fax numbers
5. Email addresses
6. SSN, MRN, Account numbers
7. Device/Vehicle identifiers
8. URLs, IP addresses
9. Biometric identifiers
10. Photos
11. And more...
$3
- โ
Run MedScrub API locally on trusted infrastructure
- โ
Use strong API keys
- โ
Review detected entities before proceeding
- โ
Delete sessions when done
- โ Don't send PHI directly to external AI without de-identifying
- โ Don't store session IDs with PHI in same location
๐ ๏ธ Development
$3
`bash
cd mcp-serverInstall dependencies
npm installBuild TypeScript
npm run buildRun locally
npm start
`$3
`
mcp-server/
โโโ src/
โ โโโ index.ts # MCP server entry point
โ โโโ client.ts # MedScrub API client
โ โโโ tools.ts # Tool implementations
โ โโโ resources.ts # Documentation resources
โโโ dist/ # Compiled JavaScript
โโโ package.json
โโโ tsconfig.json
โโโ README.md
`๐ Troubleshooting
$3
Problem: "Tool not found" or MCP server doesn't appear
Recommended Solution (Use npx):
1. Update your config to use
npx (always gets latest version):
`json
{
"mcpServers": {
"medscrub": {
"command": "npx",
"args": ["-y", "@medscrub/mcp"],
"env": {
"MEDSCRUB_API_URL": "https://api.medscrub.dev",
"MEDSCRUB_JWT_TOKEN": "your-jwt-token"
}
}
}
}
`2. Verify config file location:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json
- Linux: ~/.config/Claude/claude_desktop_config.json3. Verify JSON syntax is valid (use jsonlint.com)
4. Restart Claude Desktop completely
Alternative Solution (If npx fails):
If
npx doesn't work due to npm corruption across multiple Node versions:1. Install package globally:
`bash
npm install -g @medscrub/mcp
`2. Find your paths:
`bash
# macOS/Linux
which node
npm root -g # Windows
where node
npm root -g
`3. Update config with direct node execution:
`json
{
"mcpServers": {
"medscrub": {
"command": "/path/to/node",
"args": ["/path/to/global/node_modules/@medscrub/mcp/dist/index.js"],
"env": {
"MEDSCRUB_API_URL": "https://api.medscrub.dev",
"MEDSCRUB_JWT_TOKEN": "your-jwt-token"
}
}
}
}
` Example paths:
- macOS (nvm):
/Users/username/.nvm/versions/node/v22.15.0/bin/node and /Users/username/.nvm/versions/node/v22.15.0/lib/node_modules/@medscrub/mcp/dist/index.js
- macOS (Homebrew): /opt/homebrew/bin/node and /opt/homebrew/lib/node_modules/@medscrub/mcp/dist/index.js
- Windows: C:\Program Files\nodejs\node.exe and C:\Users\username\AppData\Roaming\npm\node_modules\@medscrub\mcp\dist\index.js
- Linux: /usr/bin/node and /usr/lib/node_modules/@medscrub/mcp/dist/index.js4. Restart Claude Desktop completely
> Note: With the direct path method, you'll need to manually update by running
npm install -g @medscrub/mcp when new versions are released.$3
1. Verify Docker container is running (for local deployment):
`bash
docker ps | grep medscrub
`2. Check API health:
`bash
curl http://localhost:3000/health
# or for production
curl https://api.medscrub.dev/health
`3. Verify API_URL in MCP config matches your deployment
$3
For hosted API (recommended):
1. Get a valid JWT token from medscrub.dev/dashboard/jwt
2. JWT tokens expire after 24 hours - generate a new one if expired
3. Use
MEDSCRUB_JWT_TOKEN (not MEDSCRUB_API_KEY) in your config:
`json
{
"env": {
"MEDSCRUB_API_URL": "https://api.medscrub.dev",
"MEDSCRUB_JWT_TOKEN": "your-jwt-token-here"
}
}
`
4. Make sure you're using version 0.1.11+ of the MCP server (use npx to get latest automatically)For API keys (local deployment):
1. Verify the key format is
msk_live_ or msk_test_ followed by 32 alphanumeric characters
2. Check MEDSCRUB_API_KEY in Claude Desktop config matches your key
3. For local deployment: Check .env file has correct API_KEY`Sessions expire after 24 hours (default). Create a new de-identification to get a fresh session ID.
Problem: "Cannot find module 'node:path'" or npx fails
Solution: Use direct node execution with global installation instead of npx (see "Alternative Solution" in MCP Server Not Loading section above)
Why this happens: npm can become corrupted across different Node versions, especially when using nvm or multiple Node installations. The direct path method bypasses npx entirely.
- MedScrub Documentation: docs.medscrub.dev
- Docker API README: ../README.md
- MCP Protocol: modelcontextprotocol.io
- HIPAA Safe Harbor: HHS.gov
Contributions welcome! Please see main CONTRIBUTING.md.
MIT License - see LICENSE
- Issues: GitHub Issues
- Email: support@medscrub.dev
- Community: Join JupyterCon Healthcare AI Community
---
Built with โค๏ธ for Healthcare AI Development
Enable safe AI adoption in healthcare workflows