Quick start on a Mac¶

This page takes you from nothing to a first working FHIR Frog session on macOS (Apple Silicon or Intel), with Claude Desktop or Claude Code. It takes about ten minutes plus the downloads.

Status: beta. The Homebrew formula is tested on Linuxbrew from the real release; it has not yet been run on a Mac, and the two Mac-specific steps below (Claude Desktop's PATH and the skill upload) are written from how those apps are documented to behave, not from a test on your machine. If any step does not work as written, please tell us: that is exactly what this beta is for.

What you need¶

Homebrew (https://brew.sh). It installs Java for you.
Claude Desktop and/or Claude Code.
Docker Desktop, only if you want FHIR Frog to start a local test server and test runner for you. Give it at least 4 GB of memory (Docker Desktop, Settings, Resources). Everything else works without it.

1. Install the server¶

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

You should see fhir-frog-mcp 0.1.0. Homebrew installs openjdk@17 as a dependency. (No Homebrew? Download the jar from the release page and run it with any Java 17+: see Install.)

Find out where Homebrew lives, you need it in step 3:

brew --prefix        # /opt/homebrew on Apple Silicon, /usr/local on Intel

2. Install the skill¶

The skill is what teaches Claude the FHIR Frog workflow and where the published docs are wrong. Download fhir-frog-skill-0.1.0.zip from the release page.

Claude Desktop: Settings, Capabilities (the menu wording changes between versions), Skills, upload the zip.
Claude Code:

mkdir -p ~/.claude/skills
unzip fhir-frog-skill-0.1.0.zip -d ~/.claude/skills

3. Connect your assistant¶

Pick a folder for your FHIR work, for example ~/frog-workspace: mkdir -p ~/frog-workspace. FHIR Frog can only read and write inside it.

Claude Desktop. Open (or create) ~/Library/Application Support/Claude/claude_desktop_config.json and add the server. Replace /opt/homebrew with your brew --prefix and YOU with your user name:

{
  "mcpServers": {
    "fhir-frog": {
      "command": "/opt/homebrew/bin/fhir-frog-mcp",
      "args": [],
      "env": {
        "FROG_WORKSPACE": "/Users/YOU/frog-workspace",
        "PATH": "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin"
      }
    }
  }
}

Two details matter on a Mac. Claude Desktop is a normal app, so it does not see the PATH from your terminal: use the absolute path for command, as above, otherwise it cannot find the program. The PATH line lets the server find Docker Desktop's docker command. Then quit Claude Desktop completely (Cmd+Q) and start it again.

Claude Code.

claude mcp add fhir-frog -e FROG_WORKSPACE=$HOME/frog-workspace -- $(brew --prefix)/bin/fhir-frog-mcp

4. Check it works¶

Start a new conversation and ask:

Run frog_doctor and tell me what is missing.

You should get a list of checks. Java should be ok. If Docker Desktop is not running you will see a warning about Docker: that only matters for the local test server.

5. Your first run¶

With Docker Desktop running, ask Claude:

Scaffold a test IG called hello in my workspace, start a local test server, and run the starter test.

Claude will show you a plan before it starts anything and wait for your approval. The first start downloads two container images and the test server needs about a minute to come up. If something fails, ask "why did that fail?": it can read the test report and tell you the cause.

More things to try are on the workflows page; the safety rules (what it will and will not do without asking) are on the safety page.

If something goes wrong¶

Symptom	Likely cause and fix
Claude Desktop shows the server as failed, log says `ENOENT` or "command not found"	`command` is not the absolute path. Use `$(brew --prefix)/bin/fhir-frog-mcp`
`frog_doctor` says docker is missing although Docker Desktop is running	The `PATH` entry is missing from the config `env` block, or Docker Desktop is not started
`docker_unavailable` when starting the local server	Start Docker Desktop and wait until it says it is running
Server start times out or the Mac slows down	Raise Docker Desktop's memory to 4 GB or more; close other heavy apps
`path_outside_workspace`	FHIR Frog only works inside `FROG_WORKSPACE`; put your files there or change the setting
Nothing happens after editing the config	Quit Claude Desktop with Cmd+Q and reopen; closing the window is not enough

More error codes and fixes: Troubleshooting. To uninstall: brew uninstall fhir-frog-mcp and remove the entry from your config.