Skip to main content

​
Configuration

Add the following to your Claude Desktop configuration file:
Edit ~/Library/Application Support/Claude/claude_desktop_config.json:
{
  "mcpServers": {
    "open-wearables": {
      "command": "uv",
      "args": [
        "run",
        "--frozen",
        "--directory",
        "/path/to/open-wearables/mcp",
        "start"
      ]
    }
  }
}
Replace /path/to/open-wearables/mcp with the actual path to the MCP directory on your system.
If the server fails to start, you may need to use the full path to uv instead of just "uv". You can find it by running:
which uv
# e.g. /Users/bart/.local/bin/uv
Then replace "command": "uv" with the full path, e.g. "command": "/Users/bart/.local/bin/uv".

​
Verifying the Connection

After configuring Claude Desktop:
  1. Restart Claude Desktop
  2. Look for the MCP tools icon in the chat interface
  3. Try asking: “Who can I query health data for?”
If configured correctly, Claude will use the get_users tool to fetch available users from your Open Wearables instance.

​
Troubleshooting

​
”Invalid API key” error

Ensure your OPEN_WEARABLES_API_KEY in config/.env is valid. You can get an API key from:
  1. The Open Wearables developer portal
  2. Or via the backend admin panel at /api/v1/developer/api-keys

​
”Connection refused” error

Make sure the backend is running at the URL specified in OPEN_WEARABLES_API_URL. For local development: 
# From project root
docker compose up -d

​
No users found

Make sure OPEN_WEARABLES_API_URL in mcp/config/.env points to the API base URL (e.g. https://api.openwearables.io or http://localhost:8000), not the URL of your Open Wearables dashboard/frontend. The MCP server calls GET /api/v1/users on this URL - if it points to the wrong service, you’ll get a 404 (“Resource not found”).