Apple Health Data with Elasticsearch

MCP Server for Apple Health Data with Elasticsearch - Starter Project

Welcome! This repository contains the complete and final source code for the blog post, "Unlock Your LLM's Potential: Building an MCP Server with Elasticsearch for Real Health Data".

This project provides a runnable implementation of a custom Model Context Protocol (MCP) server. Built with Python and the FastMCP framework, this server connects to an Elasticsearch index containing sample Apple HealthKit step data. This setup allows an LLM client like Claude to query personal health data using natural language.

Before you begin, ensure you have the following installed and running:

- Python 3.10+
- Elasticsearch: An instance of Elasticsearch 8.x running locally athttp://localhost:9200.
- Claude Desktop: The MCP client we will use to interact with the server.
- uv: For managing Python packages.

Follow these steps to set up your local environment and install the necessary dependencies.

Open your terminal or command prompt and navigate to the project folder.

cd path/to/your/folder/apple-watch-health-mcp

This step creates thepyproject.tomlfile, whichuvuses to manage your project's dependencies.

3. Create and Activate a Virtual Environment

# Create the virtual environment uv venv # Activate the environment # On macOS/Linux: source .venv/bin/activate # On Windows: .venv\Scripts\activate

Install the necessary Python packages. Note that we are specifying a compatible version for theelasticsearchlibrary to match the v8.x server used in this tutorial.

uv add "mcp[cli]" "elasticsearch>=8.0.0,<9.0.0" aiohttp pydantic

After creating the API key in Elasticsearch, you need to configure it in your environment:

# Export the API key for the current session export ES_API_KEY="your_encoded_api_key_here"

With the environment set up, you can now run the solution.

First, run the provided script to populate your Elasticsearch instance with the sample data. This script will create the index with the correct mapping and insert the 30 sample documents.

You should see output confirming that the documents were ingested successfully.

Before installing in Claude, you can verify that the server is working correctly using the MCP Inspector tool.

This will open a web interface where you can interactively test the server's resources, tools, and prompts.

This is the final step to connect your MCP server to the Claude Desktop client.
-

Install the server: Run this command in your terminal.

mcp install apple_watch_mcp.py --name "Apple Health Steps"

This command registers the server in Claude Desktop's configuration file.

Run the command below to view the contents of this file.

cat ~/Library/Application\ Support/Claude/claude_desktop_config.json

You should see a structure similar to this inside the file, under the "mcpServers" key:

{ "mcpServers": { "Apple Health Steps": { "command": "/full/path/to/your/uv", "args": [ "--directory", "/path/to/repository/apple-watch-health-mcp", "run", "apple_watch_mcp.py" // Other arguments may appear depending on your setup ] } // ... other servers might be listed here } }

-

Restart Claude Desktop: Youmustclose and reopen the Claude Desktop application for it to load the new server configuration.

Start Chatting: Once restarted, Claude will automatically run your MCP server in the background. You can now ask it questions about your health data in natural language. Try these examples from the blog post:

- "What was my most active day this week?"
- "Compare my activity between Apple Watch and iPhone"
- Or use the built-in slash commands like/daily_reportor/trend_analysis.

- apple_watch_mcp.py: Thecomplete and final scriptfor the MCP server, containing all implemented Resources, Tools, and Prompts.
- ingest_data.py: A helper script that populates your Elasticsearch instance with the sample data.
- sample_data.json: A JSON file containing fictitious Apple Health step count data for testing.
- README.md: This file, providing instructions to run the complete solution.

Unified MCP server giving AI coding agents direct access to your databases: 70+ SQL databases via SqlKit (PostgreSQL, MySQL, SQL Server, SQLite, ClickHouse, Snowflake, BigQuery) and NoSQL via DocKit (Elasticsearch, MongoDB, DynamoDB). Local-first: credentials never leave your machine, read-only by default, 79 tools.

Official MCP server for dbt (data build tool) providing integration with dbt Core/Cloud CLI, project metadata discovery, model information, and semantic layer querying capabilities.

Build robust data workflows, integrations, and analytics on a single intuitive platform.

Query and analyze data with MotherDuck and local DuckDB

Query Apple Health data using natural language and SQL.

An MCP server for querying and interacting with AWS Athena.

Access and cache Google Cloud BigQuery metadata.

Explore, query, and manage data in Google BigQuery.