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.

Related MCP server: MCP Healthcare Server

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.