icd10-mcp-server

ICD-10 MCP Server

A high-performance Model Context Protocol (MCP) server for ICD-10 medical code lookups, built with TypeScript and SQLite with Full-Text Search (FTS5) for sub-millisecond query performance.

Features

• 🚀 Blazing Fast: Sub-millisecond lookups with SQLite FTS5
• 📚 Comprehensive: 22,999 official ICD-10-CM codes from CMS.gov
• 🔍 Smart Search: Handles both medical terminology and colloquial terms
• 🏥 Medical Synonyms: Built-in medical terminology mapping (e.g., "heart attack" → myocardial infarction)
• 📊 Full Hierarchy: Navigate parent/child/sibling code relationships
• ✅ Validation: Bulk validate codes with billable status checking
• 🔄 Annual Updates: Easy updates with official CMS releases

Performance

With the full CMS dataset (22,999 codes):

• Cold start: 0.28ms (target: <500ms) ✅ 1,785x faster
• Exact lookup: 0.01ms avg (target: <10ms) ✅ 1,000x faster
• Fuzzy search: 0.12ms avg (target: <50ms) ✅ 416x faster
• Hierarchy traversal: 0.36ms avg (target: <25ms) ✅ 69x faster
• Bulk validation: 0.05ms for 105 codes (target: <100ms) ✅ 2,000x faster

Installation

# Clone the repository
git clone https://github.com/haasonsaas/icd10-mcp-server.git
cd icd10-mcp-server

# Install dependencies
npm install

# Build the project
npm run build

# Load the full ICD-10 dataset
npm run load-full-data

Claude Desktop Setup

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "icd10-mcp-server": {
      "command": "node",
      "args": ["/path/to/icd10-mcp-server/dist/index.js"]
    }
  }
}

Restart Claude Desktop after configuration.

Available Tools

1. icd10_lookup - Exact Code Lookup

// Example: Look up a specific ICD-10 code
{
  "code": "E119",
  "include_hierarchy": true,
  "effective_date": "2024-10-01"
}

2. icd10_search - Smart Search

// Example: Search using medical or colloquial terms
{
  "query": "heart attack",  // or "myocardial infarction"
  "limit": 20,
  "billable_only": true
}

Supports colloquial terms:

• "broken arm" → fracture codes
• "heart attack" → myocardial infarction
• "high blood pressure" → hypertension
• "can't breathe" → dyspnea

3. icd10_validate_batch - Bulk Validation

// Example: Validate multiple codes at once
{
  "codes": ["E119", "I10", "INVALID123"],
  "check_billable": true
}

4. icd10_hierarchy - Navigate Relationships

// Example: Get all diabetes complication codes
{
  "code": "E11",
  "direction": "children",  // or "parents", "siblings"
  "max_depth": 2
}

Medical Terminology Support

The server includes an extensible medical synonym system:

{
  "colloquial_to_medical": {
    "broken": ["fracture", "fractured"],
    "heart attack": ["myocardial infarction", "MI", "cardiac arrest"],
    "stroke": ["cerebrovascular accident", "CVA"],
    "high blood pressure": ["hypertension"],
    "sugar": ["diabetes", "glucose"]
  }
}

Add custom synonyms:

# Edit src/config/medical-synonyms.json
npm run load-synonyms

Development

# Development with auto-reload
npm run dev

# Run tests
npm test

# Type checking
npm run typecheck

# Linting
npm run lint

# Benchmark performance
npm run benchmark

Data Sources

• Primary: CMS.gov ICD-10-CM (Official annual releases)
• Updates: Released annually on October 1st

Architecture

• TypeScript + Node.js for type safety and performance
• SQLite with FTS5 for full-text search capabilities
• better-sqlite3 for synchronous, high-performance database access
• MCP SDK for Model Context Protocol integration
• Zod for runtime type validation

Scripts

• npm run load-full-data - Download and load the complete CMS dataset
• npm run load-synonyms - Load medical terminology mappings
• npm run benchmark - Run performance benchmarks
• npm run download-cms - Download latest CMS data files
• npm run parse-cms - Parse CMS files into database

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License - see file for details.

Author

Created by Jonathan Haas

Acknowledgments

• ICD-10-CM codes provided by the Centers for Medicare & Medicaid Services (CMS)
• Built for use with Claude Desktop and the Model Context Protocol