README.md

---
title: MedCodeMCP
emoji: 💬
colorFrom: yellow
colorTo: purple
sdk: gradio
sdk_version: 5.33.0
app_file: app.py
pinned: false
license: apache-2.0
short_description: an MCP Tool for Symptom-to-ICD Diagnosis Mapping.
tags:
  - mcp-server-track
  - agent-demo-track
---

MedCodeMCP is a voice-enabled medical diagnosis assistant that maps patient symptoms to probable ICD-10 codes and explanations. It leverages automatic speech recognition (ASR) (via Whisper) to transcribe spoken complaints and then engages an interactive Q&A session with the user to clarify symptoms.

Under the hood, it uses a Large Language Model (LLM) to either ask focused follow-up questions or output a final diagnosis suggestion in JSON format (with fields for diagnoses and confidence scores). The application integrates a vector database of ICD-10 descriptions using LlamaIndex for retrieval: given symptoms, it finds relevant ICD-10 code information to inform the LLM’s reasoning.

# Features

- **Automatic speech recognition (ASR)**: Transcribe real-time patient audio using [Gradio](https://www.gradio.app/guides/real-time-speech-recognition).
- **Interactive Q&A Agent**: The LLM dynamically asks clarifying questions base on ICD codes until it can diagnose with high confidence.
- **ICD-10 Mapping**: Use LlamaIndex for vector retrieval of probable ICD-10 codes with confidence scores.
- **MCP-Server Ready**: Exposes a `/mcp` REST endpoint for seamless agent integration.

# Video Demos

Short video demo for the hackathon mcp-server-track requirements:
.

Short video demo for the hackathon agent-demo-track requirements:
https://www.youtube.com/watch?v=87IQBRX7Ifk

Long form demo, explaination of idea, and work session:
https://www.youtube.com/watch?v=fqFxyp3qvSA

More work sessions:
https://www.youtube.com/watch?v=jgmut0-9KYE
https://www.youtube.com/watch?v=2xW3kOYCDP8

# Spaces

My submission for this hackathon:
https://huggingface.co/spaces/Agents-MCP-Hackathon/MedCodeMCP

A backup on my personal space:
https://huggingface.co/spaces/gpaasch/Grahams_Gradio_Agents_MCP_Hackathon_2025_Submission

## Clone & Install  
```bash
git clone https://huggingface.co/spaces/Agents-MCP-Hackathon/MedCodeMCP
cd MedCodeMCP
python3 -m venv .venv && source .venv/bin/activate  
pip install -r requirements.txt
````     |

## Launch Locally

Open [http://localhost:7860](http://localhost:7860) to interact with the app.

## MCP API Usage

```bash
curl -X POST http://localhost:7860/mcp \
  -H "Content-Type: application/json" \
  -d '{"tool":"transcribe_and_respond","input":{"audio":"<base64_audio>","history":[]}}'
```

## Project Structure

```
├── app.py                      # HF entrypoint
├── src/app.py                  # Core Gradio & agent logic
├── utils/llama_index_utils.py  # LLM predictor & indexing utils
├── data/icd10cm_tabular_2025/  # ICD-10 dataset
├── requirements.txt            # Dependencies
└── README.md                   # This file
```

# Hackathon Timeline

Here are the key dates for the Gradio Agents & MCP Hackathon:

* **May 20 – 26, 2025**: Pre-Hackathon announcements period.
* **June 2 – 10, 2025**: Official hackathon window (sign-ups remain open).
* **June 3, 2025 — 9 AM PST / 4 PM UTC**: Live kickoff YouTube event.
* **June 4 – 5, 2025**: Gradio Office Hours with MCP Support, MistralAI, LlamaIndex, Custom Components team, and Sambanova.
* **June 10, 2025 — 11:59 PM UTC**: Final submission deadline.
* **June 11 – 16, 2025**: Judging period.
* **June 17, 2025**: Winners announced.

# Key Players

## Sponsors

* **Modal Labs**: \$250 GPU/CPU credits to every participant ([modal.com](https://modal.com)).
* **Hugging Face**: \$25 API credits to every participant ([huggingface.co](https://huggingface.co)).
* **Nebius**: \$25 API credits to first 3,300 participants ([nebius.com](https://nebius.com)).
* **Anthropic**: \$25 API credits to first 1,000 participants ([anthropic.com](https://www.anthropic.com)).
* **OpenAI**: \$25 API credits to first 1,000 participants ([openai.com](https://openai.com)).
* **Hyperbolic Labs**: \$15 API credits to first 1,000 participants ([hyperbolic.xyz](https://hyperbolic.xyz)).
* **MistralAI**: \$25 API credits to first 500 participants ([mistral.ai](https://mistral.ai)).
* **Sambanova.AI**: \$25 API credits to first 250 participants ([sambanova.ai](https://sambanova.ai)). ([huggingface.co](https://huggingface.co/Agents-MCP-Hackathon))

## Panel of Judges

Judging will be conducted by representatives from sponsor partners and the Hugging Face community team, including Modal Labs, MistralAI, LlamaIndex, Sambanova.AI, and Hugging Face. To be properly judged, ensure the project is in the [proper space](https://huggingface.co/Agents-MCP-Hackathon) on hugging face, not just in a personal space. Click join organization, then click new to create a space that will be judged.

## Office Hours Hosts

* **Abubakar Abid** (MCP Support) — [@abidlabs](https://huggingface.co/abidlabs)
* **MistralAI Office Hours** — [Watch on YouTube](https://www.youtube.com/watch?v=TkyeUckXc-0)
* **LlamaIndex Office Hours** — [Watch on YouTube](https://www.youtube.com/watch?v=Ac1sh8MTQ2w)
* **Custom Components Office Hours** — [Watch on YouTube](https://www.youtube.com/watch?v=DHskahJ2e-c)
* **Sambanova Office Hours** — [Watch on YouTube](https://www.youtube.com/watch?v=h82Z7qcjgnU)

## Primary Organizers

* **Yuvraj Sharma (Yuvi)** (@yvrjsharma) — Machine Learning Engineer & Developer Advocate, Gradio Team at Hugging Face
* **Abubakar Abid** (@abidlabs) — Developer Advocate & MCP Support Lead at Hugging Face
* **Gradio Team at Hugging Face** — Core organizing team providing platform infrastructure, logistics, and community coordination

# Resources

* **Hackathon Org & Registration**: [Agents-MCP-Hackathon](https://huggingface.co/Agents-MCP-Hackathon)
* **Discord**: [discord.gg/agents-mcp-hackathon](https://discord.gg/agents-mcp-hackathon)
* **Slides from Kickoff**: [PDF](https://huggingface.co/spaces/Agents-MCP-Hackathon/README/blob/main/Gradio%20x%20Agents%20x%20MCP%20Hackathon.pdf)
* **Code of Conduct**: [Contributor Covenant](https://huggingface.co/code-of-conduct)
* **Submission Guidelines**: See “Submission Guidelines” on the hackathon page
* **MCP Guide**: [How to Build an MCP Server](https://huggingface.co/blog/gradio-mcp)
* **Gradio Docs**: [https://www.gradio.app/docs](https://www.gradio.app/docs)
* **LlamaIndex Docs**: [https://llamaindex.ai/docs](https://llamaindex.ai/docs)
* **Mistral Model Hub**: [https://huggingface.co/mistral-ai/mistral-small](https://huggingface.co/mistral-ai/mistral-small)

## Free Credits!

**Modal Labs Compute Credits** (\$250 per participant)
  Monitor your GPU/CPU credit usage by logging into your Modal account and navigating to **Dashboard → Billing**:
  [https://modal.com/dashboard](https://modal.com/dashboard) ([huggingface.co][1], [modal.com][2])

**Hugging Face API Credits** (\$25 per participant)
  View your remaining credits and invoices on the Hugging Face billing dashboard:
  [https://huggingface.co/settings/billing](https://huggingface.co/settings/billing) ([huggingface.co][1], [huggingface.co][3])

**Nebius AI Cloud Credits** (\$25 to first 3,300 participants)
  Check your Nebius “Grants and promocodes” balance and detailed billing reports at:
  [https://nebius.com/services/billing](https://nebius.com/services/billing) ([huggingface.co][1], [nebius.com][4])

**Anthropic Claude API Credits** (\$25 to first 1,000 participants)
  Track your Claude usage and remaining credits in the Anthropic Console under **Settings → Billing**:
  [https://console.anthropic.com/settings/billing](https://console.anthropic.com/settings/billing) ([huggingface.co][1])

**OpenAI API Credits** (\$25 to first 1,000 participants)
  Monitor your API calls, token usage, and spend on the OpenAI Usage dashboard:
  [https://platform.openai.com/account/usage](https://platform.openai.com/account/usage) ([huggingface.co][1], [platform.openai.com][5])

**Hyperbolic Labs API Credits** (\$15 to first 1,000 participants)
  After logging in at the Hyperbolic AI Dashboard, go to **Settings → Billing** to view your credit balance and transaction history:
  [https://app.hyperbolic.xyz](https://app.hyperbolic.xyz) ([huggingface.co][1], [docs.hyperbolic.xyz][6], [hyperbolic.xyz][7])

**Mistral AI API Credits** (\$25 to first 500 participants)
  Sign in at the Mistral Console and navigate to **Workspace → Billing** to activate and monitor your credits:
  [https://console.mistral.ai](https://console.mistral.ai) ([huggingface.co][1], [docs.mistral.ai][8])

**SambaNova AI Cloud Credits** (\$25 to first 250 participants)
  Log in to SambaNova Cloud and check your **Billing & Usage** in the plans section:
  [https://cloud.sambanova.ai/plans/billing](https://cloud.sambanova.ai/plans/billing) ([huggingface.co][1], [cloud.sambanova.ai][9])

[1]: https://huggingface.co/Agents-MCP-Hackathon "Agents-MCP-Hackathon (Agents-MCP-Hackathon)"
[2]: https://modal.com/ "Modal: High-performance AI infrastructure"
[3]: https://huggingface.co/docs/hub/billing?utm_source=chatgpt.com "Billing - Hugging Face"
[4]: https://nebius.com/services/billing?utm_source=chatgpt.com "Billing - Nebius"
[5]: https://platform.openai.com/account/usage?utm_source=chatgpt.com "Account Usage - OpenAI Platform"
[6]: https://docs.hyperbolic.xyz/docs/getting-started?utm_source=chatgpt.com "Hyperbolic API"
[7]: https://hyperbolic.xyz/blog/how-to-set-up-your-account-on-hyperbolic?utm_source=chatgpt.com "How to Set Up Your Account on Hyperbolic"
[8]: https://docs.mistral.ai/getting-started/quickstart/?utm_source=chatgpt.com "Quickstart | Mistral AI Large Language Models"
[9]: https://cloud.sambanova.ai/plans/billing?utm_source=chatgpt.com "Billing - SambaNova Cloud"

# About the Author

**Graham Paasch** is an AI realist passionate about the coming AI revolution.

* LinkedIn: [https://www.linkedin.com/in/grahampaasch/](https://www.linkedin.com/in/grahampaasch/)
* YouTube: [https://www.youtube.com/channel/UCg3oUjrSYcqsL9rGk1g\_lPQ](https://www.youtube.com/channel/UCg3oUjrSYcqsL9rGk1g_lPQ)

Graham is currently looking for work. Inspired by Leopold Aschenbrenner’s “AI Situational Awareness” ([https://situational-awareness.ai/](https://situational-awareness.ai/)), he believes AI will become a multi-trillion-dollar industry over the next decade—what we’re seeing now is the equivalent of ARPANET in the early days of the internet. He’s committed to aligning his work with this vision to stay at the forefront of the AI revolution.