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

1. Clone and setup:

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

2. Install dependencies:

   pip install -r requirements.txt

3. Set up environment variables:

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

4. Test the server:

   python mcp_server.py

Claude Desktop Configuration

1. Find your Claude Desktop config:

   • Mac: ~/Library/Application Support/Claude/claude_desktop_config.json

   • Create the file if it doesn't exist

2. 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" } } } }

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

Usage

1. Document Ingestion

Process a PDF file:

Process raw text:

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:

Edit as needed, then add to graph:

3. Query the Knowledge Graph

Ask natural language questions:

4. Graph Management

Get statistics:

Clear the graph (caution!):

Advanced Configuration

Using Alternative LLMs

BioGPT (specialized medical model):

Local Ollama model:

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:

Add to Claude config:

Example Workflow

1. Start with a textbook chapter:

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

2. Review the extraction - you might see entities like:

   • Anatomy: "left ventricle", "aortic valve"

   • Processes: "cardiac cycle", "systole", "diastole"

   • Relationships: "systole FOLLOWS atrial contraction"

3. Edit and refine the JSON to add missing details or correct relationships

4. Add to graph:

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

5. 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:

Contributing

1. Fork the repository

2. Create a feature branch

3. Add tests for new functionality

4. 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