Build Your Own Medical AI Tools
MedCode is a generic framework for creating clinical decision support systems. Add your own PDFs, guidelines, and protocols - MedCode automatically extracts the content and makes it searchable through AI assistants like Claude and OpenCode.
MedCode provides the infrastructure to turn any medical documentation into AI-accessible knowledge:
| You Provide | MedCode Creates |
|---|---|
| PDF guidelines, protocols, handbooks | Searchable knowledge base |
| Calculator formulas | MCP tools your AI can use |
| Assessment criteria | Decision support functions |
| Treatment algorithms | Clinical pathway tools |
Works with any medical specialty: Cardiology, Oncology, Psychiatry, Rheumatology, Internal Medicine, Surgery, Pediatrics, etc.
git clone https://github.com/miltosdoc/medcode.git
cd medcode
python3 -m venv venv
source venv/bin/activate # Windows: venv\Scripts\activate
pip install pymupdf mcp
pip install -e .Claude Desktop - Add to config:
{
"mcpServers": {
"medcode": {
"command": "/path/to/medcode/venv/bin/python",
"args": ["-m", "medcode.mcp.server"],
"cwd": "/path/to/medcode"
}
}
}OpenCode - Add to opencode.json:
{
"mcp": {
"medcode": {
"type": "local",
"command": ["/path/to/medcode/venv/bin/python", "-m", "medcode.mcp.server"],
"enabled": true
}
}
}When you first use MedCode, your AI assistant will guide you:
AI: "I see MedCode is not configured yet. To get started:
1. Add PDF files to: /path/to/medcode/source_pdfs/
2. Tell me when you're ready and I'll process them
You can add any medical PDFs - guidelines, protocols, handbooks, etc."
You: "I added some oncology guidelines"
AI: "Processing your PDFs... Done! Found 3 documents with 45 chapters.
You can now search your knowledge base. Try asking me about any topic
in your documents."
source_pdfs/
├── nccn_breast_cancer_2024.pdf
├── asco_immunotherapy_guidelines.pdf
└── institutional_chemotherapy_protocols.pdf
↓
[MedCode processes]
↓
Searchable knowledge base with chapters, tables, and keywords
| Tool | Description |
|---|---|
medcode_get_setup_status | Check if configured (call first!) |
medcode_process_documents | Extract and index PDFs |
medcode_search_knowledge | Search across all documents |
medcode_get_chapter | Get full chapter content |
medcode_list_chapters | List chapters in a document |
Create your own tools by adding Python files:
medcode/
├── calculators/ # Add your risk scores, dosing calculators
├── assessments/ # Add severity grading, intervention decisions
└── pathways/ # Add treatment algorithms
cp ~/Downloads/nccn_*.pdf source_pdfs/
cp ~/Downloads/asco_*.pdf source_pdfs/Tell your AI: "Process my documents"
AI: "Processing PDFs...
Processed 5 documents:
- nccn_breast_cancer (32 chapters, 15 tables)
- nccn_lung_cancer (28 chapters, 12 tables)
- asco_immunotherapy (18 chapters, 8 tables)
...
Your knowledge base is ready!"
You: "What are the first-line treatments for HER2+ breast cancer?"
AI: [Searches your NCCN guidelines]
"According to your NCCN Breast Cancer guidelines, first-line treatment
for HER2+ metastatic breast cancer includes:
- Taxane + trastuzumab + pertuzumab (Category 1)
- ...
Source: NCCN Breast Cancer v2.2024, Chapter: HER2-Positive Disease"
Copy the template and customize:
# medcode/calculators/creatinine_clearance.pyfrommedcode.core.calculatorimportBaseCalculator, to_float, to_intclassCockcroftGault(BaseCalculator):
name="creatinine_clearance"description="Calculate creatinine clearance using Cockcroft-Gault"defcalculate(self, age: str, weight_kg: str, creatinine: str, female: str="false", **kwargs):
age_val=to_int(age)
weight=to_float(weight_kg)
scr=to_float(creatinine)
is_female=female.lower() =="true"crcl= ((140-age_val) *weight) / (72*scr)
ifis_female:
crcl*=0.85return {
"creatinine_clearance": round(crcl, 1),
"unit": "mL/min",
"interpretation": self._interpret(crcl),
}
def_interpret(self, crcl):
ifcrcl>=90: return"Normal"elifcrcl>=60: return"Mild impairment"elifcrcl>=30: return"Moderate impairment"elifcrcl>=15: return"Severe impairment"else: return"Kidney failure"MedCode works with any medical specialty. Here are some ideas:
| Specialty | What to Add |
|---|---|
| Oncology | NCCN guidelines, ASCO guidelines, chemotherapy protocols |
| Cardiology | ESC guidelines, ACC/AHA guidelines, cath lab protocols |
| Psychiatry | DSM criteria, medication guides, therapy protocols |
| Rheumatology | ACR guidelines, biologics protocols, disease criteria |
| Infectious Disease | Sanford Guide, antibiotic stewardship protocols |
| Critical Care | SCCM guidelines, ventilator protocols, sepsis bundles |
Want a ready-to-use cardiology implementation? Check out CardioCode - MedCode pre-configured with 11 ESC guidelines and 50+ clinical tools.
medcode/
├── medcode/
│ ├── mcp/ # MCP server and tools
│ ├── core/ # Base classes (Calculator, Assessment, Pathway)
│ ├── knowledge/ # PDF extraction and search
│ ├── calculators/ # Your custom calculators (empty)
│ ├── assessments/ # Your custom assessments (empty)
│ ├── pathways/ # Your custom pathways (empty)
│ ├── templates/ # Copy these to create your tools
│ └── examples/ # Reference implementations
├── source_pdfs/ # Add your PDFs here
├── README.md
└── pyproject.toml
We welcome contributions! Ideas for expansion:
- Pre-built specialty packs (oncology, psychiatry, rheumatology)
- Additional calculator templates
- Improved PDF extraction for complex layouts
- Support for other document formats (Word, Excel)
MedCode is a framework for building clinical decision support tools. It is not a medical device and should not be used for direct patient care without physician oversight. Always validate extracted content against source documents.
MIT License - Free for clinical, research, and educational use.
Your Knowledge. Your AI. Your Way.
Build clinical decision support for any specialty.