medical-mcp-agent

Overview 🩺

medical-mcp-agent is a Python-based AI-powered medical assistant prototype that combines Groq's Llama-3.3-70b model, real-time PubMed literature search, and a Model Context Protocol (MCP) server.

It provides three interfaces:

• FastAPI REST API backend for structured diagnostic JSON responses
• Streamlit web dashboard for an interactive dark-themed clinical assistant experience
• FastMCP server exposing medical tools to LLM clients

This repository is designed for clinical decision support research and prototyping, not for actual medical diagnosis.

Table of Contents 📚

• Features
• Tech Stack
• Project Structure
• Installation
• Usage
  • Run FastAPI
  • Run Streamlit
  • Run MCP Server
• MCP Tools
• Environment Variables
• Example API Request
• Disclaimer

Features ✨

• Extracts medical symptoms from natural language patient descriptions using AI
• Generates ranked differential diagnoses, home remedies, treatments, and red-flag warnings
• Searches and fetches real research articles from the NCBI PubMed database
• Summarizes medical research abstracts into concise 3-4 line insights using AI
• Beautiful dark-themed Streamlit dashboard with symptom tags, expandable article cards, and emergency warning banners
• FastAPI REST endpoint: POST /diagnosis
• MCP server with four callable tools for LLM agents

Tech Stack 🧠

• Python 3.12
• Groq API with Llama-3.3-70b-versatile
• FastAPI + Uvicorn for REST backend
• Streamlit for web UI
• FastMCP for MCP server framework
• NCBI PubMed Entrez API for medical literature search
• BeautifulSoup4 + lxml for HTML/XML parsing
• uv as the Python package manager

Project Structure 🗂️

medical-mcp-agent/
├── src/
│   ├── core/
│   │   ├── config.py               # Groq client setup
│   │   ├── symptom_extractor.py    # AI symptom extraction
│   │   ├── diagnosis_symptoms.py   # AI diagnosis generation
│   │   ├── pubmed_articles.py      # PubMed search and fetch
│   │   └── summarize_pubmed.py     # AI abstract summarization
│   ├── app/
│   │   ├── api.py                  # FastAPI backend
│   │   └── streamlit.py            # Streamlit web dashboard
│   └── mcp/
│       └── server.py               # FastMCP MCP server
├── .env                            # API keys
├── pyproject.toml                  # Project dependencies
└── requirements.txt

Installation ⚙️

1. Clone the repository:

git clone https://github.com/your-username/medical-mcp-agent.git
cd medical-mcp-agent

2. Create a .env file in the project root with your Groq API key:

GROQ_API_KEY=your_key_here

3. Install dependencies with uv:

uv sync

Always prefix commands with PYTHONPATH=. when running from the project root.

Usage 🚀

Run FastAPI

Start the REST backend using the repository root:

PYTHONPATH=. python src/app/api.py

The API exposes:

• POST /diagnosis

Run Streamlit

Open the Streamlit dashboard with:

PYTHONPATH=. uv run streamlit run src/app/streamlit.py

Run MCP Server

Launch the MCP server for LLM integrations:

PYTHONPATH=. uv run fastmcp dev inspector src/mcp/server.py

MCP Tools 🧩

The MCP server exposes the following callable tools:

1. extract_patient_symptoms — Extracts symptoms from natural language text
2. generate_differential_diagnosis — Generates diagnoses from a list of symptoms
3. search_pubmed_literature — Searches NCBI PubMed and returns article metadata
4. synthesize_medical_abstracts — Summarizes medical research abstracts

These tools allow LLM clients to request structured medical assistance through MCP-aware workflows.

Environment Variables 🔐

Create a .env file and add the following variable:

GROQ_API_KEY=your_key_here

The Groq API key is required for all AI-powered operations.

Example API Request 🧪

Send a patient description to the FastAPI endpoint:

curl -X POST http://127.0.0.1:8000/diagnosis \
  -H "Content-Type: application/json" \
  -d '{"patient_description": "36-year-old female with fever, cough, and chest pain."}'

The response returns structured JSON with symptoms, differential diagnosis, treatments, and alerts.

Notes 📝

• The Streamlit dashboard includes symptom tags, article cards, and warning banners for urgent issues.
• The PubMed integration searches the NCBI Entrez API and parses results with BeautifulSoup.
• The MCP server supports integration with external LLM agents and tool-based workflows.

Disclaimer ⚠️

This repository is a clinical decision support prototype and NOT a replacement for professional medical advice.

Use this project for experimentation, research, and learning only. Always consult a licensed healthcare professional for real medical decisions.