Installing FHIR Frog MCP Server¶

This page describes how to install and configure the FHIR Frog MCP server so that an AI assistant (Claude Desktop, Claude Code, or Kiro) can use the FHIR Frog tools.

Prerequisites¶

Java 17 or later (for JAR mode)
Docker Engine 24+ (for Docker mode, or for either mode if you want to run frog-runner containers)
An AI assistant that supports MCP: Claude Desktop, Claude Code, or Kiro CLI

Platform and distribution overview¶

Platform	Homebrew	.deb package	JAR (direct)	Container image	Scoop	Chocolatey
macOS	beta (`fhirfrog/tap`)	—	✓	✓	—	—
Debian / Ubuntu	—	beta (#7)	✓	✓	—	—
Windows	—	—	✓	✓	beta (#5)	beta (#5)

Choose a distribution mode¶

Mode	Best for	Requires
Homebrew	macOS, easy install and upgrades	macOS, Homebrew
.deb	Debian / Ubuntu, system install	Debian/Ubuntu, dpkg/apt
Scoop	Windows, easy install and upgrades	Windows, Scoop
Chocolatey	Windows, enterprise / IT managed	Windows, Chocolatey
JAR	Local development, any platform	Java 17
Docker	Isolation, reproducible builds	Docker, socket mount

Option 0: Homebrew (macOS)¶

Beta: the formula is verified on Linuxbrew and not yet on a Mac. The tap lives on GitLab, so brew tap needs its URL once:

brew tap fhirfrog/tap https://gitlab.com/fhirfrog/homebrew-tap
brew install fhirfrog/tap/fhir-frog-mcp

Homebrew installs openjdk@17 as a dependency if it is not already present. Upgrades: brew update && brew upgrade fhir-frog-mcp.

Verify¶

fhir-frog-mcp --version

Print the client config snippet¶

bash scripts/print-client-config.sh --client claude-desktop --mode brew
bash scripts/print-client-config.sh --client claude-code    --mode brew
bash scripts/print-client-config.sh --client kiro           --mode brew

Replace <YOUR_WORKSPACE_PATH> in the printed JSON with the absolute path to your FHIR IG workspace directory.

Configure Claude Desktop (Homebrew)¶

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "fhir-frog": {
      "command": "/opt/homebrew/bin/fhir-frog-mcp",
      "args": [],
      "env": {
        "FROG_WORKSPACE": "/absolute/path/to/your/ig-workspace",
        "PATH": "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin"
      }
    }
  }
}

Use the absolute path ($(brew --prefix)/bin/fhir-frog-mcp: /opt/homebrew on Apple Silicon, /usr/local on Intel). Claude Desktop is a GUI app and does not see your shell PATH, so a bare fhir-frog-mcp is not found; the PATH entry also lets it find Docker Desktop's docker command. The full walk-through for Mac users is in Quick start on a Mac.

Configure Kiro (Homebrew)¶

Add to .kiro/settings/mcp.json in your workspace root:

{
  "mcpServers": {
    "fhir-frog": {
      "command": "/opt/homebrew/bin/fhir-frog-mcp",
      "args": [],
      "env": {
        "FROG_WORKSPACE": "/absolute/path/to/your/ig-workspace",
        "PATH": "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Option 1: Debian / Ubuntu (.deb)¶

Beta (#7): the package is built reproducibly, passes lintian, and was installed and run (including an MCP tools/list over stdio) in clean Debian 12 and Ubuntu 22.04/24.04 containers. A signed apt repository is planned. See issue #7.

Download the .deb¶

Download fhir-frog-mcp_0.1.0-1_all.deb from the v0.1.0 release page.

Install¶

sudo apt install ./fhir-frog-mcp_0.1.0-1_all.deb

apt installs a Java 17+ runtime automatically if one is not already present (via the openjdk-17-jre-headless | java17-runtime-headless | openjdk-21-jre-headless | java21-runtime-headless dependency).

Upgrades: when a new .deb is published, download it and re-run sudo apt install ./....

Verify¶

fhir-frog-mcp --version

Print the client config snippet¶

bash scripts/print-client-config.sh --client claude-desktop --mode deb
bash scripts/print-client-config.sh --client claude-code    --mode deb
bash scripts/print-client-config.sh --client kiro           --mode deb

Replace <YOUR_WORKSPACE_PATH> in the printed JSON with the absolute path to your FHIR IG workspace directory.

Configure Claude Desktop (Debian / Ubuntu)¶

Add to ~/.config/claude/claude_desktop_config.json:

{
  "mcpServers": {
    "fhir-frog": {
      "command": "fhir-frog-mcp",
      "args": [],
      "env": {
        "FROG_WORKSPACE": "/absolute/path/to/your/ig-workspace"
      }
    }
  }
}

Configure Claude Code (Debian / Ubuntu)¶

Add to .mcp.json in your workspace root:

{
  "mcpServers": {
    "fhir-frog": {
      "command": "fhir-frog-mcp",
      "args": [],
      "env": {
        "FROG_WORKSPACE": "/absolute/path/to/your/ig-workspace"
      }
    }
  }
}

Configure Kiro (Debian / Ubuntu)¶

Add to .kiro/settings/mcp.json in your workspace root:

{
  "mcpServers": {
    "fhir-frog": {
      "command": "fhir-frog-mcp",
      "args": [],
      "env": {
        "FROG_WORKSPACE": "/absolute/path/to/your/ig-workspace"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Option 2: JAR mode¶

Download the shaded JAR¶

Download the latest release from the GitLab package registry or 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

JAR size is approximately 155 MB (includes the full HAPI FHIR validation stack).

Print the client config snippet¶

Use the helper script to get the JSON to paste into your client:

bash scripts/print-client-config.sh --client claude-desktop --mode jar
bash scripts/print-client-config.sh --client claude-code    --mode jar
bash scripts/print-client-config.sh --client kiro           --mode jar

Replace <YOUR_WORKSPACE_PATH> in the printed JSON with the absolute path to your FHIR IG workspace directory.

Important — Claude Desktop working directory: Claude Desktop starts MCP servers with working directory /, which the OS sandbox may refuse for file operations. Always set FROG_WORKSPACE to an absolute path in the config.

Configure Claude Desktop¶

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or ~/.config/claude/claude_desktop_config.json (Linux):

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

Configure Kiro¶

Add to .kiro/settings/mcp.json in your workspace root:

{
  "mcpServers": {
    "fhir-frog": {
      "command": "java",
      "args": ["-jar", "/absolute/path/to/fhir-frog-mcp-<version>-all.jar"],
      "env": {
        "FROG_WORKSPACE": "/absolute/path/to/your/ig-workspace"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Option 3: Docker mode¶

Pull the image¶

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

Run manually (for testing)¶

docker run -i --rm \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v "$PWD":/workspace \
  -e FROG_WORKSPACE=/workspace \
  -e FROG_WORKSPACE_HOST="$PWD" \
  --network frog-net \
  registry.gitlab.com/fhirfrog/fhir-frog-mcp:latest

Network setup¶

The MCP server creates the Docker network frog-net automatically on the first call to frog_runner_start_local. If you start the container with --network frog-net before the network exists, Docker will fail.

Recommended ordering:

Create the network once:
```
docker network create frog-net
```
Start your AI assistant with the MCP config using --network frog-net.

Alternatively, omit --network frog-net from the first run; the MCP will create the network and you can add the flag to subsequent runs.

Print the client config snippet (Docker mode)¶

bash scripts/print-client-config.sh --client claude-desktop --mode docker
bash scripts/print-client-config.sh --client claude-code    --mode docker
bash scripts/print-client-config.sh --client kiro           --mode docker

Configure Claude Desktop (Docker mode)¶

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

Option 4: Windows — Scoop¶

Scoop is a command-line installer for Windows that manages packages from buckets (package repositories). Scoop installs java/temurin17-jre automatically as a dependency.

Install via Scoop¶

Beta: the manifest is generated and structurally validated but has not been run on Windows. The bucket is public at https://gitlab.com/fhirfrog/scoop-bucket.

scoop bucket add java
scoop bucket add fhirfrog https://gitlab.com/fhirfrog/scoop-bucket
scoop install fhirfrog/fhir-frog-mcp

This installs the fhir-frog-mcp command onto your PATH. Upgrades: scoop update fhir-frog-mcp.

Verify¶

fhir-frog-mcp --version

Print the client config snippet (Windows)¶

From a bash shell (Git Bash, WSL, or similar):

bash scripts/print-client-config.sh --client claude-desktop --mode windows
bash scripts/print-client-config.sh --client claude-code    --mode windows
bash scripts/print-client-config.sh --client kiro           --mode windows

Replace C:\\Users\\you\\workspace in the printed JSON with the absolute path to your FHIR IG workspace directory (use JSON-escaped backslashes: \\).

Configure Claude Desktop (Windows — Scoop)¶

Add to %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "fhir-frog": {
      "command": "fhir-frog-mcp",
      "args": [],
      "env": {
        "FROG_WORKSPACE": "C:\\Users\\you\\your-fhir-ig-workspace"
      }
    }
  }
}

Important: Claude Desktop must be restarted after editing this file.

FROG_CONFIG_DIR defaults to %USERPROFILE%\.fhir-frog. Set it explicitly only if you want a different location.

Configure Claude Code (Windows — Scoop)¶

Add to .mcp.json in your workspace root:

{
  "mcpServers": {
    "fhir-frog": {
      "command": "fhir-frog-mcp",
      "args": [],
      "env": {
        "FROG_WORKSPACE": "C:\\Users\\you\\your-fhir-ig-workspace"
      }
    }
  }
}

Configure Kiro (Windows — Scoop)¶

Add to .kiro/settings/mcp.json in your workspace root:

{
  "mcpServers": {
    "fhir-frog": {
      "command": "fhir-frog-mcp",
      "args": [],
      "env": {
        "FROG_WORKSPACE": "C:\\Users\\you\\your-fhir-ig-workspace"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Option 5: Windows — Chocolatey¶

Chocolatey is a Windows package manager suitable for enterprise and IT-managed environments. The FHIR Frog MCP Chocolatey package installs temurin17 as a dependency and shims fhir-frog-mcp onto the system PATH.

Note: The package is published to this project's GitLab NuGet feed (not to the Chocolatey community repository, which moderates submissions). It is generated and structurally validated, GitLab reads its metadata correctly, but it has not yet been run on Windows. See GitLab issue #5.

Install via Chocolatey¶

choco source add -n fhirfrog -s https://gitlab.com/api/v4/projects/87883606/packages/nuget/index.json
choco install fhir-frog-mcp

The feed is anonymous read. Once installed, fhir-frog-mcp is on your PATH. Upgrades: choco upgrade fhir-frog-mcp.

Configure Claude Desktop (Windows — Chocolatey)¶

Same as the Scoop configuration above — the command name is identical:

{
  "mcpServers": {
    "fhir-frog": {
      "command": "fhir-frog-mcp",
      "args": [],
      "env": {
        "FROG_WORKSPACE": "C:\\Users\\you\\your-fhir-ig-workspace"
      }
    }
  }
}

Important: Claude Desktop must be restarted after editing this file.

The FHIR Frog MCP container uses the Docker client only — there is no nested Docker daemon inside the container. The MCP communicates with the host Docker daemon via the mounted socket (/var/run/docker.sock:/var/run/docker.sock).

This creates the following constraints:

Host-path volume mounts¶

When the MCP starts a frog-runner container (via frog_runner_start_local), it constructs docker run -v <path>:/workspace arguments. The path must be a host-side path — the path as seen by the Docker daemon, not the /workspace path inside the MCP container.

That is why FROG_WORKSPACE_HOST is required: set it to the same absolute directory you pass as the -v source.

CI environments (GitLab CI DinD)¶

In GitLab CI pipelines that use the docker:dind service, the Docker daemon listens on tcp://docker:2375 (or 2376 with TLS). Set:

variables:
  DOCKER_HOST: tcp://docker:2375
  DOCKER_TLS_CERTDIR: ""

The socket path (/var/run/docker.sock) will not exist; pass -e DOCKER_HOST=tcp://docker:2375 to the MCP container instead of the socket mount.

File ownership¶

Files created inside /workspace by frog-runner containers are owned by the uid used by that container. If the MCP container runs as uid 1000 (frogmcp) and the frog-runner runs as a different uid, you may see permission differences on the host.

macOS Docker Desktop¶

On macOS, the Docker socket is a proxy at /var/run/docker.sock (or ~/.docker/run/docker.sock). Volume mounts must use paths visible inside the Docker Desktop Linux VM. Paths under your home directory work by default because Docker Desktop maps ~ into the VM. Paths outside your home (e.g. /opt) may need an explicit file sharing entry in Docker Desktop preferences.

Verify the installation¶

# JAR mode
java -jar /path/to/fhir-frog-mcp-<version>-all.jar --version

# Docker mode
docker run --rm registry.gitlab.com/fhirfrog/fhir-frog-mcp:latest --version

JAR size note¶

The shaded JAR is approximately 155 MB. This size is dominated by the HAPI FHIR validation stack:

Dependency	Size	Why included
org.hl7.fhir.r4	13 MB	R4 model classes (required)
org.hl7.fhir.r5	12 MB	R5 model classes (required by converter chain)
org.hl7.fhir.dstu3	9.6 MB	STU3 converters (required by hapi-fhir-converter)
hapi-fhir-validation-resources-r4	5.5 MB	R4 profiles and terminology
Other HAPI / MCP SDK	~115 MB	Runtime and MCP protocol

No safe exclusions were found that would not break frog_run_local or frog_tsh_compile. The hapi-fhir-structures-r4 and hapi-fhir-structures-r5 jars are only 30 KB each (model stubs); the bulk is in the core org.hl7.fhir.* model artifacts which are all required by the validation pipeline.

For Mac users: the first download is ~155 MB. Subsequent docker pulls use layer caching and are much smaller on incremental updates.