Cardiology Knowledge Graph MCP Server

A Model Context Protocol (MCP) server that creates and queries a cardiology knowledge graph using Neo4j and LLM-powered entity extraction.

Features

📚 Document Ingestion: Process PDF files or raw text to extract cardiology entities and relationships
🧠 LLM-Powered Extraction: Uses GPT-4 (or customizable models like BioGPT) for intelligent extraction
📊 Knowledge Graph: Stores data in Neo4j with proper relationships
🔍 Natural Language Queries: Query the graph using plain English
✏️ Human-in-the-Loop: Review and edit extractions before adding to graph
📈 Graph Analytics: Get statistics and insights about your knowledge graph

Prerequisites

1. Neo4j Setup

Option A (Recommended): Download Neo4j Desktop for Mac
- Create a new database with these credentials:
  - URI: bolt://localhost:7687
  - Username: neo4j
  - Password: password (or your choice)
- Start the database
Option B: Use Neo4j Aura (free cloud instance)
- Update connection details in your environment variables

2. API Key

Get an OpenAI API key from OpenAI Platform
Or set up alternative models (see Configuration section)

Installation

Clone and setup:

git clone <your-repo>
cd "Cardiology Knowledge Graph MCP"

Install dependencies:
```
pip install -r requirements.txt
```

Set up environment variables:

cp .env.example .env
# Edit .env with your actual values

Test the server:
```
python mcp_server.py
```

Claude Desktop Configuration

Find your Claude Desktop config:
- Mac: ~/Library/Application Support/Claude/claude_desktop_config.json
- Create the file if it doesn't exist

Add the MCP server configuration:

{
  "mcpServers": {
    "cardiology-kg": {
      "command": "python",
      "args": ["/full/path/to/your/mcp_server.py"],
      "env": {
        "NEO4J_URI": "bolt://localhost:7687",
        "NEO4J_USERNAME": "neo4j",
        "NEO4J_PASSWORD": "your-password",
        "OPENAI_API_KEY": "your-openai-key"
      }
    }
  }
}

Restart Claude Desktop and look for the 🔨 hammer icon to confirm the server is connected.

Usage

1. Document Ingestion

Process a PDF file:

Ingest this cardiology document: /path/to/cardiology-textbook-chapter.pdf

Process raw text:

Ingest this cardiology note: "Patient presents with atrial fibrillation. Echocardiogram shows left ventricular hypertrophy. Prescribed metoprolol for rate control."

The system will:

Extract entities (conditions, medications, procedures, anatomy)
Identify relationships (causes, treats, affects, etc.)
Return a draft JSON for your review

2. Review and Edit Extractions

After ingestion, you'll get a draft like:

{
  "entities": [
    {"name": "atrial fibrillation", "label": "Condition", "properties": {}},
    {"name": "metoprolol", "label": "Medication", "properties": {"class": "beta-blocker"}}
  ],
  "relationships": [
    {"source": "metoprolol", "target": "atrial fibrillation", "type": "TREATS", "properties": {"purpose": "rate control"}}
  ]
}

Edit as needed, then add to graph:

Add this to my knowledge graph: [paste your edited JSON]

3. Query the Knowledge Graph

Ask natural language questions:

What medications treat atrial fibrillation?
How does left ventricular hypertrophy affect cardiac function?
Show me all conditions that cause heart failure.
What procedures are used to diagnose coronary artery disease?

4. Graph Management

Get statistics:

Show me statistics about my cardiology knowledge graph

Clear the graph (caution!):

Clear my knowledge graph

Advanced Configuration

Using Alternative LLMs

BioGPT (specialized medical model):

# Uncomment in mcp_server.py:
from langchain_huggingface import HuggingFaceHub
llm = HuggingFaceHub(repo_id="microsoft/BioGPT")

Local Ollama model:

# Uncomment in mcp_server.py:
from langchain_community.llms import Ollama
llm = Ollama(model="llama2")  # or "biomedical-llm"

Custom Entity Types and Relationships

Edit the extraction prompt in mcp_server.py to focus on specific:

Anatomical structures
Drug classes
Diagnostic criteria
Treatment protocols

Integration with Neo4j Official MCP Servers

Install additional Neo4j MCP servers for enhanced capabilities:

pip install mcp-neo4j-cypher mcp-neo4j-memory

Add to Claude config:

{
  "mcpServers": {
    "cardiology-kg": { /* your custom server */ },
    "neo4j-cypher": {
      "command": "mcp-neo4j-cypher",
      "args": ["--db-url", "bolt://localhost:7687", "--user", "neo4j", "--password", "password"]
    }
  }
}

Example Workflow

Start with a textbook chapter:

Ingest this PDF: /Users/you/Downloads/cardiac-physiology-chapter.pdf

Review the extraction - you might see entities like:
- Anatomy: "left ventricle", "aortic valve"
- Processes: "cardiac cycle", "systole", "diastole"
- Relationships: "systole FOLLOWS atrial contraction"
Edit and refine the JSON to add missing details or correct relationships

Add to graph:

Add this to my knowledge graph: [your refined JSON]

Query for insights:

Explain the cardiac cycle based on my knowledge graph
What anatomical structures are involved in systole?
How do beta-blockers affect the cardiac cycle?

Troubleshooting

Common Issues

"Connection refused" error:

Ensure Neo4j database is running
Check connection details in environment variables

"API key not found":

Verify OPENAI_API_KEY is set correctly
Check Claude Desktop config environment variables

"Module not found" errors:

Run pip install -r requirements.txt again
Check Python virtual environment

MCP server not appearing in Claude:

Verify the full path to mcp_server.py in config
Restart Claude Desktop completely
Check logs in Claude Desktop (Help → Show Logs)

Logs and Debugging

The server logs helpful information. To see detailed logs:

python mcp_server.py 2>&1 | tee server.log

Contributing

Fork the repository
Create a feature branch
Add tests for new functionality
Submit a pull request

License

MIT License - see LICENSE file for details.

Acknowledgments

Built on the Model Context Protocol by Anthropic
Uses Neo4j for graph database capabilities
Powered by LangChain for LLM integration
Inspired by medical informatics and knowledge representation research