How to add Apple Health MCP Server to Windsurf

Query your Apple Health data with natural language via Elasticsearch, ClickHouse, or DuckDB. Paste the config into ~/.codeium/windsurf/mcp_config.json and restart Windsurf.

Last updated June 14, 2026 · 213★ · stdio · no auth

Windsurf config for Apple Health MCP Server

git clone https://github.com/the-momentum/apple-health-mcp-server

{
  "mcpServers": {
    "apple-health-mcp-server": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--init",
        "--mount",
        "type=bind,source=<project-path>/{xml-file-name}.xml,target=/root_project/raw.xml",
        "--mount",
        "type=bind,source=<project-path>/config/.env,target=/root_project/config/.env",
        "-e",
        "ES_HOST=host.docker.internal",
        "mcp-server:latest"
      ]
    }
  }
}

Requires Docker to be installed and running.

Setup steps

1Open Windsurf → Cascade → the hammer/MCP icon → Configure (or edit ~/.codeium/windsurf/mcp_config.json).
2Paste the Apple Health MCP Server config below.
3Fill in placeholder secrets, then save.
4Click Refresh in the MCP panel.
5Apple Health MCP Server's tools become available to Cascade.

Before you start

Docker (recommended) or uv for dependency management
Clone the repository and copy config/.env.example to config/.env
An Apple Health data export as an XML file placed on your filesystem
A backing store populated from the XML: Elasticsearch (make es), ClickHouse (make ch), or DuckDB (make duckdb)

What Apple Health MCP Server can do in Windsurf

get_xml_structure

Analyze the structure and metadata of your Apple Health XML export (file size, tags, types).

search_xml_content

Search for specific content in the XML file (by attribute value, device, type, etc.).

get_xml_by_type

Extract all records of a specific health record type from the XML file.

get_health_summary_es

Get a summary of all Apple Health data in Elasticsearch (total count, type breakdown, etc.).

search_health_records_es

Flexible search for health records in Elasticsearch with advanced filtering and query options.

get_statistics_by_type_es

Get comprehensive statistics (count, min, max, avg, sum) for a specific health record type in Elasticsearch.

get_trend_data_es

Analyze trends for a health record type over time (daily, weekly, monthly, yearly) in Elasticsearch.

search_values_es

Search Elasticsearch for records with exactly matching values (including text).

Security

Runs locally and reads your exported Apple Health XML data from your filesystem; no external API key is required. The Docker config mounts your health data file, the app directory, and your config/.env into the container. Apple Health data is sensitive personal health information, so keep your exports and config private.

Apple Health MCP Server + Windsurf FAQ

Where is the Windsurf config file?

Windsurf reads MCP servers from ~/.codeium/windsurf/mcp_config.json. Paste the Apple Health MCP Server config there under the "mcpServers" key and restart the client.

Is Apple Health MCP Server safe to use with Windsurf?

Which databases are supported as a backend?

Elasticsearch, ClickHouse, and DuckDB. You populate the chosen backend from your Apple Health XML export using make es, make ch, or make duckdb.

How do I get my Apple Health data in?

Export your Apple Health data as an XML file from your iPhone, place it on your filesystem (the project root by default), and import it into your chosen backend before running the server.

How do I run it with an MCP client?

Either via Docker (recommended) by building the image with make build and adding the docker-mcp-server config, or locally with uv run by adding the uv-mcp-server config. Both are stdio-based and added to your LLM client's mcpServers settings.

View repo Full Apple Health MCP Server page