Setting Up Your Local Environment¶

This guide walks through verifying and setting up your machine to use FHIR Frog: Java, Docker, the MCP server, and optional tools like the IG Publisher and terminology server.

System requirements¶

Component	Minimum	Recommended	Optional
Java	17	17+	No (only if using JAR mode; Docker image includes Java)
Docker	24	24+	For local runner, local SUT, or Docker mode MCP
Docker disk space	10 GB	20+ GB	Multiple FHIR servers, test data
Docker memory	2 GB (JAR + local engine)	4–6 GB (with local runner + SUT)	Required for SUT + runner together
Python	3.8	3.10+	Optional, for some helper scripts

Step 1: Run frog_doctor¶

The first tool you should call every session is frog_doctor. It checks your environment and reports what is working and what needs attention:

frog_doctor()

Output (example):

✓ docker: ok                              (Docker daemon 24.0.6, socket /var/run/docker.sock)
✓ java: ok                                (openjdk 17.0.1, /usr/bin/java)
✓ maven: ok                               (3.8.1, /usr/bin/mvn)
✗ docker-memory: warn                     (2 GB; 4 GB recommended for local runner + SUT)
✓ registry-credentials: ok                (registry.gitlab.com authenticated)
✓ fhir-packages-cache: ok                 (~/.fhir/packages, 8 GB, 15 packages)
✓ sushi: ok                               (2.8.0)
✓ ig-publisher: ok                        (1.4.38)
✓ fpl: ok                                 (0.1.2)
⚠ port-8080: available
⚠ port-8081: available

Interpreting the output¶

✓ ok: No action needed.
⚠ warn: Non-fatal; hints are provided. For example, "Docker memory" warns but does not block local testing.
✗ fail: Blocks certain operations. For example, if Docker is not running, you cannot use the local runner or local SUT.

Fix failures before proceeding; see the hints in the output.

Step 2: Verify Java¶

Check that Java 17+ is installed and on your PATH:

java -version

Output (example):

openjdk version "17.0.1" 2021-10-19
OpenJDK Runtime Environment (Temurin-17.0.1+12)
OpenJDK 64-Bit Server VM (Temurin-17.0.1+12, mixed mode, sharing)

If Java is not found, install it:

Linux: apt-get install openjdk-17-jdk-headless
macOS: brew install openjdk@17
Windows: Download from adoptium.net

Then add it to your PATH:

# macOS
echo 'export PATH="/opt/homebrew/opt/openjdk@17/bin:$PATH"' >> ~/.zprofile

# Linux
export PATH="/usr/lib/jvm/openjdk-17/bin:$PATH"

Step 3: Verify Docker¶

Check that Docker daemon is running and accessible:

docker --version
docker ps

If Docker is not running:

Linux: systemctl start docker or sudo systemctl start docker
macOS: Open the Docker Desktop application
Windows: Open Docker Desktop from the Start menu

Docker permissions (Linux)¶

On Linux, if you get permission denied, add your user to the docker group:

sudo usermod -aG docker $USER

Then log out and back in (or run newgrp docker).

Step 4: Configure the MCP server¶

The MCP server can run in two modes: JAR (local) or Docker (isolated).

Option A: JAR mode (local)¶

Download or build the shaded JAR:

# Build from source
git clone https://gitlab.com/fhirfrog/fhir-frog-mcp.git
cd fhir-frog-mcp
mvn -q -B -DskipTests package
# JAR is at: target/fhir-frog-mcp-<version>-all.jar

Or download a release from the GitLab package registry.

Add to your AI client config (Claude Desktop or Kiro):

{
  "mcpServers": {
    "fhir-frog": {
      "command": "java",
      "args": ["-jar", "/absolute/path/to/fhir-frog-mcp-0.1.0-all.jar"],
      "env": {
        "FROG_WORKSPACE": "/absolute/path/to/your/workspace"
      }
    }
  }
}

Option B: Docker mode¶

Pull the Docker image:

docker pull registry.gitlab.com/fhirfrog/fhir-frog-mcp:latest

Add to your client config:

{
  "mcpServers": {
    "fhir-frog": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "/var/run/docker.sock:/var/run/docker.sock",
        "-v", "/absolute/path/to/workspace:/workspace",
        "-e", "FROG_WORKSPACE=/workspace",
        "-e", "FROG_WORKSPACE_HOST=/absolute/path/to/workspace",
        "--network", "frog-net",
        "registry.gitlab.com/fhirfrog/fhir-frog-mcp:latest"
      ]
    }
  }
}

Step 5: Set workspace path¶

The MCP needs to know where your FHIR IG workspace is. Set FROG_WORKSPACE in the MCP config (see above) or in your shell:

export FROG_WORKSPACE="/path/to/your/ig-workspace"

This should be an absolute path, not a relative one.

Step 6: Optional setup¶

IG Publisher (for building IGs)¶

Install SUSHI and the IG Publisher:

# SUSHI (FSH compiler)
npm install -g fsh-sushi

# IG Publisher
# Download from: https://github.com/HL7/fhir-ig-publisher/releases

Or let frog_doctor guide you to install them.

Maven and Ant (for CI/CD)¶

If you plan to integrate tests into a Maven or Ant build:

# Maven
apt-get install maven                # Linux
brew install maven                   # macOS

# Ant
apt-get install ant                  # Linux
brew install ant                     # macOS

Local terminology server (for advanced use)¶

For testing terminology operations ($expand, $validate-code), set up a terminology server. HAPI FHIR includes basic support; for more advanced terminology, use a dedicated server like OntoServer or add terminology service endpoints to your SUT registration.

Step 7: Verify the setup¶

Run a simple test:

# Call frog_doctor again to verify everything
frog_doctor()

# Verify the MCP is connected by asking for the tool list
# (This call is internal to the AI assistant; you do not run it directly)

In your AI assistant (Claude, Kiro), run:

Hello! Please run frog_doctor to verify my setup.

macOS-specific notes¶

Docker Desktop memory¶

Docker Desktop on macOS by default allocates 2 GB. For a local runner + SUT, increase it to 4–6 GB:

Open Docker Desktop → Preferences → Resources
Set Memory to at least 4 GB
Restart Docker Desktop

Apple Silicon (M1/M2/M3)¶

FHIR Frog images are built for both amd64 and arm64. If you pull an image, Docker selects the right architecture automatically. However:

HAPI FHIR images are available for both architectures; use the latest tag
frog-runner is available for both architectures

No special configuration needed.

File mounting in Docker Desktop¶

Paths under your home directory (~) are shared automatically with Docker. Paths outside your home may need explicit sharing:

Docker Desktop → Preferences → File Sharing
Add the path(s) you want to mount
Restart Docker Desktop

Docker socket on macOS¶

The Docker socket is at /var/run/docker.sock (or ~/.docker/run/docker.sock on newer versions). If you run the MCP in a Docker container and need to start other containers, mount the socket:

docker run ... -v /var/run/docker.sock:/var/run/docker.sock ...

Workspace structure¶

A typical FHIR IG workspace looks like this:

my-ig-workspace/
  my-ig/
    input/
      fsh/
        tests/
          search-test.tsh
      resources/
    sushi-config.yaml
  my-test-ig/
    input/
      fsh/
    sushi-config.yaml
  fixtures/
    patient.json
    observation.json

The workspace root is where you define FROG_WORKSPACE. All paths in the MCP are relative to this directory (e.g. my-ig/input/fsh/tests/search-test.tsh).

Troubleshooting¶

"Docker daemon is not running"¶

# Linux
sudo systemctl start docker

# macOS
# Open Docker Desktop application

"Connection refused: 127.0.0.1:8080"¶

The MCP is trying to reach a local runner or SUT that is not running. Start it:

frog_server_start_local(confirm: true)
frog_runner_start_local(confirm: true)

"Stale registry credentials"¶

If frog_doctor reports a warning about registry credentials:

docker logout registry.gitlab.com

Then try again. Next pull will be anonymous (works for public images).

"FROG_WORKSPACE not set"¶

The MCP needs to know your workspace path. Set it in the client config (under "env") or export it:

export FROG_WORKSPACE="/absolute/path/to/workspace"

"Out of memory"¶

If Docker runs out of memory while running a local SUT + runner:

Stop the containers: frog_server_stop(confirm: true) and frog_runner_stop(confirm: true)
Increase Docker Desktop memory (see macOS notes above, or similar for Linux)
Retry