Medical MCP Server

A Model Context Protocol (MCP) server that provides medical information tools powered by Grok AI. Works with Claude Desktop, Claude Code, and any other MCP-compatible client.

---

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
• Architecture
• Prerequisites
• Installation
• Configuration
• Usage
  • CLI (Interactive Mode)
  • Claude Desktop Integration
• Available Tools
• Available Resources
• Built-in Knowledge Base
• Project Structure
• Extending the Server
• Troubleshooting
• 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	v18 or higher
Grok API Key	Free tier available

---

Installation

# 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

cp .env.example .env

2. Add your Grok API key

Open .env and fill in:

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/
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:

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

{
  "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:

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 — MCP protocol implementation
• Grok AI by X.AI — AI backend for medical queries
• Medical data is for educational purposes only and does not replace professional medical advice