Biology Medicine and Bioinformatics Python ★ 124

wso2/fhir-mcp-server

FHIR API'leri için Model Context Protocol sunucusu. FHIR sunucularıyla sorunsuz entegrasyon sağlayarak, AI asistanlarının SMART-on-FHIR kimlik doğrulaması desteğiyle klinik sağlık verilerini arama, alma, oluşturma, güncelleme ve analiz etmelerini sağlar.

Claude Desktop config.json'a ekle

{
  "mcpServers": {
    "wso2-fhir-mcp-server": {
      "command": "python",
      "args": [
        "-m",
        "fhir_mcp_server"
      ]
    }
  }
}

Bu MCP sunucusu hakkında

Model Context Protocol (MCP) Sunucusu Fast Healthcare Interoperability Resources (FHIR) API'ları için

License Get Support on Stack Overflow Join the community on Discord X Listed on Spark Install via Spark

İçindekiler

Genel Bakış

FHIR MCP Sunucusu, FHIR API'ları ile sorunsuz entegrasyon sağlayan bir Model Context Protocol (MCP) sunucusudur. Geliştiriciler, entegratörler ve sağlık hizmetleri inovatörleri için tasarlanan bu sunucu, modern AI/LLM araçları ile sağlık verileri arasında bir köprü görevi görerek, klinik bilgileri arama, alma ve analiz etmeyi kolaylaştırır.

Demo

HAPI FHIR sunucusu ile demo

Bu video, MCP sunucusunun genel HAPI FHIR sunucusuna bağlandığında işlevselliğini göstermektedir. Bu örnek, yetkilendirme akışı gerektirmeyen açık bir FHIR sunucusu ile doğrudan etkileşimi göstermektedir.

https://github.com/user-attachments/assets/cc6ac87e-8329-4da4-a090-2d76564a3abf

EPIC Sandbox ile demo

Bu video, MCP sunucusunun Epic EHR ekosistemi içindeki yeteneklerini göstermektedir. Tam OAuth 2.0 Yetkilendirme Kodu Grant akışını göstermektedir.

https://github.com/user-attachments/assets/96b433f1-3e53-4564-8466-65ab48d521de

Temel Özellikler

  • MCP uyumlu transport: FHIR'ı stdio, SSE veya streamable HTTP üzerinden sunar

  • SMART-on-FHIR tabanlı authentication desteği: FHIR sunucuları ve istemcileri ile güvenli şekilde kimlik doğrulama yapın

  • Tool entegrasyonu: VS Code, Claude Desktop ve MCP Inspector gibi herhangi bir MCP istemcisi ile entegre edilebilir

Ön Koşullar

  • Python 3.8+
  • uv (bağımlılık yönetimi için)
  • Erişilebilir bir FHIR API sunucusu.

Kurulum

Python paketimizi yükleyerek veya bu repository'yi klonlayarak FHIR MCP Sunucusunu kullanabilirsiniz.

PyPI Paketi Kullanarak Kurulum

  1. Ortam Değişkenlerini Yapılandırın:

    Sunucuyu çalıştırmak için FHIR_SERVER_BASE_URL ayarlamanız gerekir.

    • Yetkilendirmeyi etkinleştirmek için: FHIR_SERVER_BASE_URL, FHIR_SERVER_CLIENT_ID, FHIR_SERVER_CLIENT_SECRET ve FHIR_SERVER_SCOPES ayarlayın. Yetkilendirme varsayılan olarak etkindir.
    • Yetkilendirmeyi devre dışı bırakmak için: FHIR_SERVER_DISABLE_AUTHORIZATION değerini True olarak ayarlayın.

    Varsayılan olarak, MCP sunucusu http://localhost:8000 üzerinde çalışır ve FHIR_MCP_HOST ve FHIR_MCP_PORT kullanarak host ve port'u özelleştirebilirsiniz.

    Bunları aşağıdaki gibi ortam değişkenleri olarak ayarlayabilir veya bir .env dosyası oluşturabilirsiniz (.env.example referansı alarak).

    export FHIR_SERVER_BASE_URL=""
export FHIR_SERVER_CLIENT_ID=""
export FHIR_SERVER_CLIENT_SECRET=""
export FHIR_SERVER_SCOPES=""

export FHIR_MCP_HOST="localhost"
export FHIR_MCP_PORT="8000"

  2. PyPI paketini yükleyin ve sunucuyu çalıştırın

    uvx fhir-mcp-server

Kaynaktan Kurulum

  1. Repository'yi klonlayın:

    git clone <repository_url>
cd <repository_directory>

  2. Sanal bir ortam oluşturun ve bağımlılıkları yükleyin:

    uv venv
source .venv/bin/activate
uv pip sync requirements.txt

    Veya pip ile:

    python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

  3. Ortam Değişkenlerini Yapılandırın: Örnek dosyayı kopyalayın ve gerekirse özelleştirin:

    cp .env.example .env

  4. Sunucuyu çalıştırın:

    uv run fhir-mcp-server

Docker Kullanarak Kurulum

Docker ile MCP Sunucusunu Çalıştırma

Docker'ı kullanarak MCP sunucusunu tutarlı, izole bir ortamda çalıştırabilirsiniz.

Yetkilendirme Notu: MCP sunucusunu Docker veya Docker Compose aracılığıyla yerel olarak çalıştırırken, ortam değişkeni FHIR_SERVER_DISABLE_AUTHORIZATION=True ayarlanarak yetkilendirme devre dışı bırakılmalıdır. Bu gelecek sürümlerde düzeltilecektir.

  1. Docker Image'ını oluşturun veya container registry'den docker image'ını çekin:

    • Kaynaktan oluşturun:
      docker build -t fhir-mcp-server .
    • GitHub Container Registry'den çekin:
      docker pull wso2/fhir-mcp-server:latest

  2. Ortam Değişkenlerini Yapılandırın

    Örnek ortam dosyasını kopyalayın ve gerekirse düzenleyin:

    cp .env.example .env
# FHIR sunucunuzu, istemci kimlik bilgilerinizi vb. ayarlamak için .env dosyasını düzenleyin

    Alternatif olarak, ortam değişkenlerini doğrudan -e flag'leri ile veya hassas değerler için Docker secrets'leri kullanarak geçirebilirsiniz. Kullanılabilir ortam değişkenleri hakkında ayrıntılar için Yapılandırma bölümüne bakın.

  3. Container'ı Çalıştırın

    docker run --env-file .env -p 8000:8000 fhir-mcp-server

    Bu, sunucuyu başlatacak ve port 8000'de kullanıma sunacaktır. Gerekirse port eşlemesini ayarlayın.

HAPI FHIR Sunucusu ile Docker Compose Kullanma

FHIR MCP sunucusu ve HAPI FHIR sunucusu (PostgreSQL ile) dahil olmak üzere hızlı bir kurulum için sağlanan docker-compose.yml dosyasını kullanın. Bu, FHIR işlemlerini test etmek için anında bir geliştirme ortamı ayarlar.

  1. Ön Koşullar:

    • Docker ve Docker Compose yüklü.

  2. Stack'i Çalıştırın:

    docker-compose up -d

    Bu komut şunları yapacaktır:

  3. Hizmetlere Erişin:

  4. Ek Ortam Değişkenlerini Yapılandırın:

    OAuth veya diğer ayarları özelleştirmeniz gerekiyorsa, docker-compose.yml dosyasındaki env değişkenlerini ayarlayın. Compose dosyası temel yapılandırma ayarlar; tam seçenekler için Yapılandırma bölümüne bakın.

MCP İstemcileri ile Entegrasyon

FHIR MCP Sunucusu çeşitli MCP istemcileri ile sorunsuz entegrasyon için tasarlanmıştır.

VS Code

Install in VS Code Install in VS Code Insiders

VS Code'da MCP yapılandırma dosyasına aşağıdaki JSON bloğunu ekleyin (> V1.104). Bunu Ctrl + Shift + P tuşlarına basıp MCP: Open User Configuration yazarak yapabilirsiniz.

Streamable HTTPSTDIOSSE
"servers": {
    "fhir": {
        "type": "http",
        "url": "http://localhost:8000/mcp",
    }
}

"servers": {
    "fhir": {
        "command": "uv",
        "args": [
            "--directory",
            "/path/to/fhir-mcp-server",
            "run",
            "fhir-mcp-server",
            "--transport",
            "stdio"
        ],
        "env": {
            "FHIR_SERVER_ACCESS_TOKEN": "Your FHIR Access Token"
        }
    }
}

"servers": {
    "fhir": {
        "type": "sse",
        "url": "http://localhost:8000/sse",
    }
}

Claude Desktop

Yerel MCP sunucunuza bağlanmak için Claude Desktop ayarlarına aşağıdaki JSON bloğunu ekleyin.

  • Claude Desktop uygulamasını başlatın, üst çubukta Claude menüsüne tıklayın ve "Settings…" öğesini seçin.
  • Settings bölmesinde, sol kenar çubuğundaki "Developer" öğesine tıklayın. Ardından "Edit Config" öğesine tıklayın. Bu, yapılandırma dosyanızı dosya sisteminizde açacaktır. Henüz yoksa, Claude otomatik olarak şu konumda bir tane oluşturacaktır:
    • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
    • Windows: %APPDATA%\Claude\claude_desktop_config.json
  • claude_desktop_config.json dosyasını herhangi bir metin editöründe açın. İçeriğini MCP sunucusunu kaydetmek için aşağıdaki JSON bloğu ile değiştirin:
Streamable HTTPSTDIOSSE
{
    "mcpServers": {
        "fhir": {
            "command": "npx",
            "args": [
                "-y",
                "mcp-remote",
                "http://localhost:8000/mcp"
            ]
        }
    }
}

{
    "mcpServers": {
        "fhir": {
            "command": "uv",
            "args": [
                "--directory",
                "/path/to/fhir-mcp-server",
                "run",
                "fhir-mcp-server",
                "--transport",
                "stdio"
            ],
            "env": {
                "FHIR_SERVER_ACCESS_TOKEN": "Your FHIR Access Token"
            }
        }
    }
}

{
    "mcpServers": {
        "fhir": {
            "command": "npx",
            "args": [
                "-y",
                "mcp-remote",
                "http://localhost:8000/sse"
            ]
        }
    }
}

MCP Inspector

MCP Inspector'ı çalışır hale getirmek için şu adımları izleyin:

  • Bir terminal açın ve aşağıdaki komutu çalıştırın:

    npx -y @modelcontextprotocol/inspector

  • MCP Inspector arayüzünde:

Streamable HTTPSTDIOSSE
  • Transport Type: Streamable HTTP
  • URL: http://localhost:8000/mcp
  • Transport Type: STDIO
  • Command: uv
  • Arguments: --directory /path/to/fhir-mcp-server run fhir-mcp-server --transport stdio
  • Transport Type: SSE
  • URL: http://localhost:8000/sse

MCP sunucunuzun zaten çalışıyor ve yukarıdaki endpoint'te dinlediğinden emin olun.

Bağlandıktan sonra, MCP Inspector tool çağrılarını görselleştirmenize, request/response payload'larını incelemenize ve tool uygulamalarınızda kolayca hata ayıklamanıza izin verecektir.

Yapılandırma

CLI Seçenekleri

MCP sunucusunun davranışını aşağıdaki command-line flag'leri kullanarak özelleştirebilirsiniz:

  • --transport

    • Açıklama: MCP sunucusunun istemcilerle iletişim kurmak için kullanması gereken transport protokolünü belirtir.
    • Kabul edilen değerler: stdio, sse, streamable-http
    • Varsayılan: streamable-http

  • --log-level

    • Açıklama: Sunucu için logging ayrıntılılık seviyesini ayarlar.
    • Kabul edilen değerler: DEBUG, INFO, WARN, ERROR (büyük/küçük harfe duyarlı değil)
    • Varsayılan: INFO

  • --help

    • Açıklama: Mevcut sunucu seçenekleri ile bir yardım mesajı görüntüler ve çıkar.
    • Kullanım: Komut satırı arayüzü tarafından otomatik olarak sağlanır.

Örnek Kullanımlar:

uv run fhir-mcp-server --transport streamable-http --log-level DEBUG
uv run fhir-mcp-server --help

Ortam Değişkenleri

MCP Sunucu Yapılandırması:

  • FHIR_MCP_HOST: MCP sunucusunun bağlanması gereken hostname veya IP adresi (örneğin, yerel erişim için localhost veya tüm arayüzler için 0.0.0.0).
  • FHIR_MCP_PORT: MCP sunucusunun gelen istemci talepleri için dinleyeceği port (örneğin, 8000).
  • FHIR_MCP_SERVER_URL: Ayarlanırsa, bu değer host ve port'tan oluşturmak yerine sunucunun temel URL'si olarak kullanılacaktır. Özel URL yapılandırmaları veya proxy arkasında olduğunuz durumlarda kullanışlıdır.
  • FHIR_MCP_REQUEST_TIMEOUT: MCP sunucusundan FHIR sunucusuna yönelik isteklerin timeout süresi (saniye cinsinden) (varsayılan: 30).

MCP Sunucu OAuth2 ve FHIR sunucusu Yapılandırması (MCP İstemci ↔ MCP Sunucu): Bu değişkenler, FHIR sunucusu ile OAuth2 authorization code grant akışı kullanan MCP istemcisinin MCP sunucusuna güvenli bağlantısını yapılandırır.

  • FHIR_SERVER_CLIENT_ID: MCP istemcilerini FHIR sunucusu ile yetkilendirmek için kullanılan OAuth2 client ID'si.
  • FHIR_SERVER_DISABLE_AUTHORIZATION: True olarak ayarlanırsa, MCP sunucusundaki yetkilendirme kontrollerini devre dışı bırakır ve herkese açık FHIR sunucularına bağlanmanıza izin verir.
  • FHIR_SERVER_CLIENT_SECRET: FHIR client ID'sine karşılık gelen client secret. Token değişimi sırasında kullanılır.
  • FHIR_SERVER_BASE_URL: FHIR sunucusunun temel URL'si (örneğin, https://hapi.fhir.org/baseR4). Bu, tool URI'lerini oluşturmak ve FHIR isteklerini yönlendirmek için kullanılır.
  • FHIR_SERVER_SCOPES: FHIR yetkilendirme sunucusundan istenecek boşluk ile ayrılmış OAuth2 scope'ların listesi (örneğin, user/Patient.read user/Observation.read). get_user tool'u için kullanıcı bağlamı alınmasını etkinleştirmek için fhirUser openid ekleyin. Bu iki scope yapılandırılmamışsa, get_user tool'u boş bir sonuç döndürür çünkü ID token'ı kullanıcının FHIR resource referansını içermez.
  • FHIR_SERVER_ACCESS_TOKEN: FHIR sunucusu için kimlik doğrulama istekleri için kullanılacak access token. Bu değişken ayarlanırsa, sunucu OAuth2 yetkilendirme akışını atlar ve tüm istekler için bu token'ı doğrudan kullanır.

Araçlar

  • get_capabilities: Belirtilen FHIR resource türü hakkında, desteklenen arama parametreleri ve custom operations dahil olmak üzere metadata alır.

    • type: FHIR resource türü adı (örneğin, "Patient", "Observation", "Encounter")

  • search: Belirtilen resource türü üzerinde standart FHIR search interaction'ını gerçekleştirir ve eşleşen resource'ların bundle'ını veya listesini döndürür.

    • type: FHIR resource türü adı (örneğin, "MedicationRequest", "Condition", "Procedure").
    • searchParam: FHIR arama parametreleri adlarının istenen değerlerine eşlemesi (örneğin, {"family":"Simpson","birthdate":"1956-05-12"}).

  • read: Bir FHIR "read" interaction'ını gerçekleştirir ve belirtilen türün ve resource ID'nin tek bir resource örneğini alır; isteğe bağlı olarak yanıtı arama parametreleri veya custom operations ile iyileştirir.

    • type: FHIR resource türü adı (örneğin, "DiagnosticReport", "AllergyIntolerance", "Immunization").
    • id: Belirli bir FHIR resource örneğinin logical ID'si.
    • searchParam: FHIR arama parametreleri adlarının istenen değerlerine eşlemesi (örneğin, {"device-name":"glucometer"}).
    • operation: Resource için tanımlanmış custom FHIR operation veya extended query'nin adı (örneğin, "$everything").

  • create: Belirtilen türün yeni resource'sını kalıcı hale getirmek için FHIR "create" interaction'ını gerçekleştirir.

    • type: FHIR resource türü adı (örneğin, "Device", "CarePlan", "Goal").
    • payload: Oluşturulacak tam FHIR resource body'sini temsil eden JSON nesnesi.
    • searchParam: FHIR arama parametreleri adlarının istenen değerlerine eşlemesi (örneğin, {"address-city":"Boston"}).
    • operation: Resource için tanımlanmış custom FHIR operation veya extended query'nin adı (örneğin, "$evaluate").

  • update: Var olan resource örneğinin içeriğini sağlanan payload ile değiştirerek FHIR "update" interaction'ını gerçekleştirir.

    • type: FHIR resource türü adı (örneğin, "Location", "Organization", "Coverage").
    • id: Belirli bir FHIR resource örneğinin logical ID'si.
    • payload: Tüm gerekli öğeleri ve tüm isteğe bağlı verileri içeren FHIR resource'nun tam JSON temsili.
    • searchParam: FHIR arama parametreleri adlarının istenen değerlerine eşlemesi (örneğin, {"patient":"Patient/54321","relationship":"father"}).
    • operation: Resource için tanımlanmış custom FHIR operation veya extended query'nin adı (örneğin, "$lastn").

  • delete: Belirtilen resource örneğinde FHIR "delete" interaction'ını gerçekleştirir.

    • type: FHIR resource türü adı (örneğin, "ServiceRequest", "Appointment", "HealthcareService").
    • id: Belirli bir FHIR resource örneğinin logical ID'si.
    • searchParam: FHIR arama parametreleri adlarının istenen değerlerine eşlemesi (örneğin, {"category":"laboratory","issued:"2025-05-01"}).
    • operation: Resource için tanımlanmış custom FHIR operation veya extended query'nin adı (örneğin, "$expand").

  • get_user: Şu anda kimlik doğrulaması yapılmış kullanıcının FHIR resource'sunu (örneğin bağlantılı Patient resource'su) alır ve id, name ve birthDate gibi mevcut demografik alanları içeren özlü bir profil döndürür.

Geliştirme ve Test

Geliştirme Bağımlılıklarını Kurma

Test'leri çalıştırmak ve geliştirmeye katkıda bulunmak için test bağımlılıklarını yükleyin:

pip Kullanarak:

# Projeyi test bağımlılıkları ile geliştirme modunda yükleyin
pip install -e '.[test]'

# Veya requirements dosyasından yükleyin
pip install -r requirements-dev.txt

uv Kullanarak:

# Geliştirme bağımlılıklarını yükleyin
uv sync --dev

Testleri Çalıştırma

Proje, tüm ana işlevselliği kapsayan kapsamlı bir test paketi içerir:

# Basit test çalıştırıcı
python run_tests.py

# Veya doğrudan pytest kullanımı
PYTHONPATH=src python -m pytest tests/ -v --cov=src/fhir_mcp_server

pytest Kullanarak:

pytest tests/

Bu, tests/ dizinindeki tüm testleri keşfedecek ve çalıştıracaktır.

Test Özellikleri:

  • 100+'dan fazla test kapsamlı kapsama ile
  • Tam async/await desteği pytest-asyncio kullanarak
  • Tam mock'lama HTTP istekleri ve harici bağımlılıklarının
  • Kapsama raporlaması terminal ve HTML çıktısı ile
  • Hızlı yürütme gerçek ağ çağrıları

Benzer MCP sunucuları

genomoncology/biomcp Biology Medicine and Bioinformatics

Biyomedikal araştırma için PubMed, ClinicalTrials.gov ve MyVariant.info verilerine erişim sağlayan MCP server.

genomoncology/biomcp ★ 529
the-momentum/apple-health-mcp-server Biology Medicine and Bioinformatics

Apple Health'ten dışa aktarılan verilere erişim sağlayan bir MCP sunucusu. Veri analitikleri dahildir.

the-momentum/apple-health-mcp-server ★ 217
Daha fazla: Biology Medicine and Bioinformatics →