# medical-mcp-agent

![Python 3.12](https://img.shields.io/badge/python-3.12-blue?logo=python)
![License: MIT](https://img.shields.io/badge/license-MIT-green)
![Groq Llama-3.3-70b](https://img.shields.io/badge/Groq-Llama--3.3--70b-orange)

## 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](#features)
- [Tech Stack](#tech-stack)
- [Project Structure](#project-structure)
- [Installation](#installation)
- [Usage](#usage)
  - [Run FastAPI](#run-fastapi)
  - [Run Streamlit](#run-streamlit)
  - [Run MCP Server](#run-mcp-server)
- [MCP Tools](#mcp-tools)
- [Environment Variables](#environment-variables)
- [Example API Request](#example-api-request)
- [Disclaimer](#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:

```bash
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:

```text
GROQ_API_KEY=your_key_here
```

3. Install dependencies with `uv`:

```bash
uv sync
```

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

## Usage 🚀

### Run FastAPI

Start the REST backend using the repository root:

```bash
PYTHONPATH=. python src/app/api.py
```

The API exposes:

- `POST /diagnosis`

### Run Streamlit

Open the Streamlit dashboard with:

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

### Run MCP Server

Launch the MCP server for LLM integrations:

```bash
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:

```text
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:

```bash
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.