This MCP server provides an interface to interact with FHIR servers using the Model Context Protocol (MCP). It exposes a set of capabilities for working with FHIR R4 resources, including creating, reading, updating, deleting, and searching resources, as well as accessing resource history and executing FHIR transactions. The server is designed for developers who want to programmatically manipulate FHIR data and generate synthetic data when paired with the Claude client for demonstrations. You can perform CRUD operations through the MCP endpoints, query resources with flexible search criteria, and inspect capabilities and version information of the connected FHIR server.

To use the server, start it with the configured runtime (dotnet in this case) and point it at your FHIR server (via the FHIR_SERVER_BASE or equivalent config). Available tools include CreateResource, ReadResource, UpdateResource, DeleteResource, SearchResources, FindNumberOfResources, GetResourceHistory, and ExecuteTransaction for FHIR transactions. You can also retrieve server capabilities and formats via GetFhirVersion, ListSupportedFormats, ListResourceTypes, and ListResourceCapabilities. For demonstrations, you can combine this MCP server with the Claude client to generate synthetic data, perform patient searches, and visualize results in a graphical representation.

If you are using the VS Code MCP server workflow, update the .vscode/mcp.json configuration to point to the local .csproj or built DLL so the editor can manage and launch the server during development.

Prerequisites:

• .NET SDK (compatible with the project, e.g., .NET 6.x or 7.x)
• Git
• Optional: Docker and Docker Compose for local FHIR servers

Installation steps:

1. Clone the repository: git clone https://github.com/quiquemz-fhir-mcp-server/repo-name.git cd repo-name

2. Restore and build the project: dotnet restore dotnet build -c Release

3. Configure environment:

   • Set the FHIR server base URL and any required credentials in the environment or configuration file.
   • Ensure the path to the FHIR server is reachable from your host.

4. Run the MCP server: dotnet run --project path/to/FhirMcpServer.csproj

   or run the built DLL directly if you have one:

   dotnet path/to/FhirMcpServer.dll

5. (Optional) Start local FHIR servers for testing using Docker Compose: docker compose up -d --wait

   This will start HAPI FHIR Server (with sample data) and Azure FHIR Server (empty DB).

6. Verify startup:

   • Check console logs for startup messages indicating active MCP endpoints.
   • Use a REST client or the MCP tooling to invoke CRUD/Search endpoints against the configured FHIR server.

Tips and common issues:

• Ensure the FHIR server base URL is reachable from the MCP server host; network or DNS issues can cause connection failures.
• If using Docker, confirm the firewall and port mappings allow MCP to communicate with the FHIR servers.
• Set LOG_LEVEL to debug during development to surface detailed information for troubleshooting.
• For VS Code users, update .vscode/mcp.json to point to your local .csproj to leverage built-in MCP server integration.
• When executing transactions, ensure the resource types and references align with the FHIR server’s supported profiles and versions.
• If you see authentication errors, provide appropriate credentials via environment variables or configuration specific to your FHIR server.