Medical GraphRAG Assistant

You operate a production-ready MCP server that enables multi-modal medical querying through a Claude/GPT/NIM-based agent. It connects to clinical text, a knowledge graph, and medical images, all orchestrated by the MCP protocol for autonomous tool use, with persistent memory and visualization capabilities to support clinical decision making.

How to use

You run the MCP server locally and connect a client that understands MCP. Start the server, then use your MCP client to point to the local stdio endpoint. The server exposes 14+ tools across FHIR search, GraphRAG, image search, memory, and visualizations. Engage the agent in natural-language questions like evaluating treatment options, locating relevant clinical notes, or exploring relationships between conditions and procedures.

How to install

Prerequisites: You need Python 3.10+ and a functioning shell. Ensure that your AWS credentials and IRIS database are accessible if you plan to run in a cloud or remote environment.

1. Install Python dependencies. Run this from the project root:

pip install -r requirements.txt

2. Set up environment variables that the server relies on. Use these as a baseline and adjust to your environment.

export AWS_PROFILE=your-profile
export IRIS_HOST=localhost
export IRIS_PORT=32782
export IRIS_NAMESPACE=%SYS
export IRIS_USERNAME=_SYSTEM
export IRIS_PASSWORD=SYS
export NVCLIP_BASE_URL="http://localhost:8002/v1"

3. Start the MCP server that exposes the GraphRAG FHIR integration. This runs as a local stdio server. Use the complete command below to launch the server. If you are using a different Python path or script location, adjust accordingly.

python mcp-server/fhir_graphrag_mcp_server.py

Configuration and run notes

• The server expects a local or accessible IRIS database with vector rows for clinical notes, X-ray images, and a knowledge graph. The NV-CLIP service is used for image embeddings and memory indexing via NV-CLIP.

• If you need to adjust the NV-CLIP endpoint, set NVCLIP_BASE_URL to the endpoint of your NV-CLIP service. If you are running locally, you can tunnel to a remote service as needed.

• The system uses a batch vectorization flow by default. Changes to FHIR documents require re-embedding steps if you update content. Plan for future automatic synchronization if you enable embedded updates.

Known tools and data sources

The MCP server provides a suite of tools that Claude or other LLMs can autonomously call to search and reason over data. Tools are categorized into FHIR search, GraphRAG queries, image search, memory operations, and visualizations.

Data sources and memory

The system ingests FHIR documents, knowledge graph data, chest X-ray images, and agent memory. It stores embeddings in a vector-optimized IRIS database and exposes them to multi-modal search pipelines.

Troubleshooting tips

Common issues include missing AWS credentials, IRIS connection failures, NV-CLIP service unavailability, or embedding/indexing problems. Verify environment variables, ensure services are reachable, and check the latest logs in the execution traces.

Available tools

search_fhir_documents

Full-text search over clinical notes in the FHIR repository using SQL-like queries and embeddings

get_document_details

Retrieve complete clinical notes by document ID for detailed review

search_knowledge_graph

Query the knowledge graph for entities and relationships such as symptoms, conditions, and medications

hybrid_search

Fusion of vector, graph, and image sources using Reciprocal Rank Fusion (RRF)

get_entity_statistics

Knowledge graph statistics and insights such as entity counts and relationship types

search_medical_images

Semantic search over chest X-rays using NV-CLIP embeddings

remember_information

Store user corrections, preferences, and knowledge in Agent Memory

recall_information

Semantic memory search to recall stored information for improved tool selection

get_memory_stats

Memory system statistics and health indicators

plot_symptom_frequency

Visualization of symptom frequency across the dataset

plot_entity_distribution

Charts showing entity type distribution

plot_patient_timeline

Timeline visualization of patient encounters and events

plot_entity_network

Knowledge graph relationship visualization

visualize_graphrag_results

Interactive visualization of GraphRAG search results