> ## Documentation Index
> Fetch the complete documentation index at: https://openwearables.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Health Data MCP Server

> The Open Wearables MCP server connects Claude Desktop and Cursor to health data. Query sleep, workouts, and activity in natural language. FastMCP-based.

## What is MCP?

MCP (Model Context Protocol) is a standard for connecting AI assistants to external data sources. The Open Wearables MCP server enables AI tools like **Claude Desktop** and **Cursor** to query your wearable health data through natural language conversations.

<Note>
  The MCP server is **decoupled** from the backend - it communicates via REST API using your API key. This means it can be deployed independently and uses existing, tested API endpoints.
</Note>

## Demo

This demo uses generated sample data to show the capabilities of Claude's MCP integration with Open Wearables. User 1 has short, irregular sleep patterns while User 2 shows longer, more consistent sleep quality. Claude analyzes both datasets to identify key differences and health implications.

<iframe width="100%" height="400" src="https://www.youtube.com/embed/Jb8N2jNbs1Y" title="Open Wearables MCP Server Demo" frameBorder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowFullScreen />

## Available Tools

The MCP server provides the following tools for AI assistants:

<CardGroup cols={2}>
  <Card title="List Users" icon="users">
    Discover users accessible via your API key. Optionally filter by name or email.
  </Card>

  <Card title="Activity Summary" icon="person-running">
    Get daily activity data including steps, calories, heart rate, and intensity minutes.
  </Card>

  <Card title="Sleep Summary" icon="bed">
    Get sleep data for a user within a date range.
  </Card>

  <Card title="Workout Events" icon="dumbbell">
    Get workout and exercise sessions for a user within a date range.
  </Card>
</CardGroup>

## Example Interactions

### Discovering users

```
User: "Who can I query health data for?"
Claude: [calls get_users()]
Claude: "I found 2 users: John Doe and Jane Smith."
```

### Querying sleep data

```
User: "How much sleep did John get last week?"
Claude: [calls get_users() to get John's user_id]
Claude: [calls get_sleep_summary(user_id="uuid-1", start_date="2026-01-28", end_date="2026-02-04")]
Claude: "John slept an average of 7 hours and 45 minutes over the last week.
His longest sleep was 8h 15m on Monday, and shortest was 6h 30m on Thursday."
```

### Generic request (no time range specified)

```
User: "Fetch workouts for John"
Claude: [calls get_users() to get John's user_id]
Claude: [defaults to last 2 weeks: calls get_workout_events(user_id="uuid-1", start_date="2026-01-21", end_date="2026-02-04")]
Claude: "Over the last 2 weeks, John completed 8 workouts..."
```

## Quick Start

### Prerequisites

* [uv](https://docs.astral.sh/uv/) package manager
* Running Open Wearables backend (or access to a deployed instance)
* Valid Open Wearables API key

### 1. Install dependencies

```bash theme={null}
cd mcp
uv sync --group code-quality
```

### 2. Configure environment

```bash theme={null}
cp config/.env.example config/.env
```

Edit `config/.env` with your settings:

```bash theme={null}
OPEN_WEARABLES_API_URL=http://localhost:8000
OPEN_WEARABLES_API_KEY=ow_your_api_key_here
```

<Tip>
  To generate your API key, go to the **Open Wearables Dashboard -> Settings -> Credentials -> Create API Key**.
</Tip>

### 3. Test the server

```bash theme={null}
uv run start
```

If the server starts successfully, you should see output similar to:

```bash theme={null}
2026-02-10 07:48:22,016 - app.main - INFO - Open Wearables MCP server initialized. API URL: http://localhost:8000
[02/10/26 07:48:22] INFO     Starting MCP server 'open-wearables' with transport 'stdio'
2026-02-10 07:48:22,048 - docket.worker - INFO - Starting worker 'MacBook-Pro-26.local#19901' with the following tasks:
2026-02-10 07:48:22,049 - docket.worker - INFO - * trace(message: str, ...)
2026-02-10 07:48:22,049 - docket.worker - INFO - * fail(message: str, ...)
2026-02-10 07:48:22,049 - docket.worker - INFO - * sleep(seconds: float, ...)
```

You can stop the server now - the LLM client you configure in the next steps will start it automatically on launch.

## Next Steps

<CardGroup cols={2}>
  <Card title="Claude Desktop Setup" icon="message-bot" href="/mcp-server/claude-desktop">
    Configure the MCP server with Claude Desktop.
  </Card>

  <Card title="Cursor Setup" icon="code" href="/mcp-server/cursor">
    Configure the MCP server with Cursor IDE.
  </Card>
</CardGroup>