# Medical MCP Server

> A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that provides medical information tools powered by **Grok AI**. Works with Claude Desktop, Claude Code, and any other MCP-compatible client.

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js](https://img.shields.io/badge/Node.js-v18%2B-green)](https://nodejs.org/)
[![MCP SDK](https://img.shields.io/badge/MCP%20SDK-1.0.4-blue)](https://github.com/modelcontextprotocol/typescript-sdk)
[![Grok AI](https://img.shields.io/badge/AI-Grok%20Beta-black)](https://x.ai/)

---

> **Disclaimer:** This server is for **EDUCATIONAL PURPOSES ONLY**. It is not a substitute for professional medical advice, diagnosis, or treatment. Always consult a qualified healthcare professional for medical concerns.

---

## Table of Contents

- [Features](#features)
- [Architecture](#architecture)
- [Prerequisites](#prerequisites)
- [Installation](#installation)
- [Configuration](#configuration)
- [Usage](#usage)
  - [CLI (Interactive Mode)](#cli-interactive-mode)
  - [Claude Desktop Integration](#claude-desktop-integration)
- [Available Tools](#available-tools)
- [Available Resources](#available-resources)
- [Built-in Knowledge Base](#built-in-knowledge-base)
- [Project Structure](#project-structure)
- [Extending the Server](#extending-the-server)
- [Troubleshooting](#troubleshooting)
- [License](#license)

---

## Features

- **Medication Information** — Uses, dosage, side effects, and warnings
- **Drug Interaction Checker** — Identify potential interactions between two medications
- **Medical Term Definitions** — Plain-language explanations of medical terminology
- **General Medical Q&A** — Powered by Grok AI for open-ended questions
- **Interactive CLI** — Terminal-based client with conversation memory and colored output
- **Claude Desktop Integration** — Plug in as an MCP server for seamless AI-assisted queries
- **Hybrid Knowledge Base** — Fast local lookups + Grok AI fallback for unknown queries
- **Safety First** — Every response includes a medical disclaimer

---

## Architecture

```
┌──────────────────────────────────────────────────────┐
│                   User / MCP Client                  │
│            (Claude Desktop · CLI · etc.)             │
└───────────────────────┬──────────────────────────────┘
                        │  stdio
                        ▼
┌──────────────────────────────────────────────────────┐
│               MCP Server  (index.js)                 │
│                                                      │
│  ┌─────────────────────┐   ┌──────────────────────┐  │
│  │  Local Knowledge DB │   │     Grok AI API      │  │
│  │  (medications,      │──▶│  (fallback for       │  │
│  │   interactions,     │   │   unknown queries)   │  │
│  │   terminology)      │   └──────────────────────┘  │
│  └─────────────────────┘                             │
│                                                      │
│  Tools: get_medication_info · check_drug_interaction │
│         define_medical_term  · ask_medical_question  │
└──────────────────────────────────────────────────────┘
```

---

## Prerequisites

| Requirement | Version |
|---|---|
| [Node.js](https://nodejs.org/) | v18 or higher |
| [Grok API Key](https://console.x.ai/) | Free tier available |

---

## Installation

```bash
# 1. Clone the repository
git clone https://github.com/your-username/medical-mcp-server.git
cd medical-mcp-server

# 2. Install dependencies
npm install
```

---

## Configuration

### 1. Create your `.env` file

```bash
cp .env.example .env
```

### 2. Add your Grok API key

Open `.env` and fill in:

```env
GROK_API_KEY=your_grok_api_key_here
GROK_API_BASE_URL=https://api.x.ai/v1   # optional, this is the default
```

**Getting a Grok API key:**
1. Visit [https://console.x.ai/](https://console.x.ai/)
2. Sign in with your X (Twitter) account
3. Go to **API Keys** → **Create new key**
4. Copy it immediately (it won't be shown again)

---

## Usage

### CLI (Interactive Mode)

Run the interactive terminal client — no MCP client needed:

```bash
npm run cli
```

Example session:

```
You: What is aspirin used for?
Assistant: Aspirin (Acetylsalicylic acid) is used for pain relief, fever reduction,
           and as a blood thinner...  [Medical Disclaimer: ...]

You: Check interactions between aspirin and ibuprofen
Assistant: ⚠️ Interaction found: Concurrent use may increase the risk of gastrointestinal
           bleeding...

You: /help      ← type /help to see available commands
You: /exit      ← exits the client
```

### Claude Desktop Integration

Add the server to your Claude Desktop config file:

**Windows** → `%APPDATA%\Claude\claude_desktop_config.json`

**macOS/Linux** → `~/Library/Application Support/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "medical": {
      "command": "node",
      "args": ["/absolute/path/to/medical-mcp-server/index.js"]
    }
  }
}
```

> Replace `/absolute/path/to/medical-mcp-server/index.js` with the actual path on your machine.

After saving:
1. Restart Claude Desktop
2. Look for the **plug icon (🔌)** to confirm the server is connected
3. Start asking medical questions in your Claude conversations

---

## Available Tools

| Tool | Description |
|---|---|
| `get_medication_info` | Detailed medication info — uses, dosage, side effects, warnings |
| `check_drug_interaction` | Checks for interactions between two medications |
| `define_medical_term` | Plain-English definitions of medical terminology |
| `ask_medical_question` | General medical Q&A via Grok AI |

### Example prompts (in Claude Desktop or CLI)

```
Can you get information about metformin?
Check if there are any interactions between aspirin and warfarin.
What does tachycardia mean?
What are the common symptoms of dehydration?
```

---

## Available Resources

| URI | Description |
|---|---|
| `medical://medications/list` | Lists all medications in the built-in knowledge base |
| `medical://disclaimer` | Full medical disclaimer text |

---

## Built-in Knowledge Base

The server ships with pre-loaded data so common queries are answered instantly without an API call:

**Medications:** Aspirin · Ibuprofen · Metformin

**Drug Interactions:** Aspirin–Ibuprofen · Aspirin–Warfarin · Metformin–Alcohol

**Medical Terms:** Hypertension · Diabetes · Tachycardia · Hypotension

All other queries fall back to Grok AI automatically.

---

## Project Structure

```
medical-mcp-server/
├── index.js          # MCP server — tools, resources, Grok integration
├── cli.js            # Interactive CLI client
├── package.json      # Dependencies and npm scripts
├── .env.example      # Environment variable template
├── .gitignore        # Ignores node_modules, .env, logs
├── QUICKSTART.md     # 5-minute setup guide
└── README.md         # This file
```

---

## Extending the Server

All extension points are in `index.js`:

**Add a new medication to the knowledge base:**
```js
MEDICAL_DATA.medications["drug-name"] = {
  name: "Drug Name",
  generic_name: "...",
  uses: [...],
  dosage: "...",
  side_effects: [...],
  warnings: [...],
};
```

**Add a new tool:**
1. Add the tool definition inside the `ListToolsRequestSchema` handler
2. Add the handler logic inside the `CallToolRequestSchema` handler

**Add a new resource:**
1. Register the URI in `ListResourcesRequestSchema`
2. Handle the URI in `ReadResourceRequestSchema`

---

## Troubleshooting

| Problem | Solution |
|---|---|
| `GROK_API_KEY is not set` | Check that `.env` exists and contains a valid key with no extra spaces or quotes |
| Server not showing in Claude Desktop | Verify the path in config is absolute and correct, then restart Claude Desktop |
| API rate limit errors | Grok API limits depend on your plan — consider caching frequent queries |
| CLI won't start | Ensure Node.js v18+ is installed (`node --version`) |

---

---

## Acknowledgments

- [Model Context Protocol SDK](https://github.com/modelcontextprotocol/typescript-sdk) — MCP protocol implementation
- [Grok AI by X.AI](https://x.ai/) — AI backend for medical queries
- Medical data is for educational purposes only and does not replace professional medical advice