Skip to main content

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.

​
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.
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.

​
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.

​
Available Tools

The MCP server provides the following tools for AI assistants:

List Users

Discover users accessible via your API key. Optionally filter by name or email.

Activity Summary

Get daily activity data including steps, calories, heart rate, and intensity minutes.

Sleep Summary

Get sleep data for a user within a date range.

Workout Events

Get workout and exercise sessions for a user within a date range.

​
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 package manager
  • Running Open Wearables backend (or access to a deployed instance)
  • Valid Open Wearables API key

​
1. Install dependencies

cd mcp
uv sync --group code-quality

​
2. Configure environment

cp config/.env.example config/.env
Edit config/.env with your settings: 
OPEN_WEARABLES_API_URL=http://localhost:8000
OPEN_WEARABLES_API_KEY=ow_your_api_key_here
To generate your API key, go to the Open Wearables Dashboard -> Settings -> Credentials -> Create API Key.

​
3. Test the server

uv run start
If the server starts successfully, you should see output similar to: 
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

Claude Desktop Setup

Configure the MCP server with Claude Desktop.

Cursor Setup

Configure the MCP server with Cursor IDE.