Sensor Bio Server

CI License: MIT

Connect your Sensor Bio wearable data to Claude, ChatGPT, and other AI assistants using the Model Context Protocol (MCP).

Ask your AI assistant things like "How did I sleep last week?", "What's my resting heart rate trend?", or "Show me my recovery scores for the past month" and get answers pulled directly from your Sensor Bio data.

---

Quick Start

1. Get your API token

Log in to your Sensor Bio developer portal and grab your Organization API Token.

2. Install uv

This server uses uv to run. Install it with one command:

Mac / Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows (PowerShell):

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

3. Add to Claude Desktop

Open your Claude Desktop config file:

OS	Path
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Windows	%APPDATA%\Claude\claude_desktop_config.json
Linux	~/.config/Claude/claude_desktop_config.json

Add (or merge into) the mcpServers section:

{
  "mcpServers": {
    "sensorbio": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/GetSensr-io/sensorbio-mcp-server",
        "sensorbio-mcp-server"
      ],
      "env": {
        "SENSR_ORG_TOKEN": "paste-your-token-here"
      }
    }
  }
}

4. Restart Claude Desktop

Quit and reopen Claude Desktop. You should see "sensorbio" in the MCP tools list (look for the hammer icon).

5. Try it out

Ask Claude something like:

"Show me my sleep data from the past week"

"How many calories did I burn yesterday?"

"List all users in my organization"

---

Other MCP Clients

Cursor / Windsurf

These editors support MCP servers natively. Use the same config format above in their respective MCP settings.

OpenAI (ChatGPT)

MCP support in ChatGPT is rolling out. When available, the same server and config pattern will work.

Any MCP Client

Any application that supports the Model Context Protocol can connect using this server. Just point it at:

uvx --from git+https://github.com/GetSensr-io/sensorbio-mcp-server sensorbio-mcp-server

---

Authentication

Method	Env Vars	Best For
API Token	SENSR_ORG_TOKEN or SENSR_API_KEY	Most users (recommended)
OAuth2	SENSR_CLIENT_ID + SENSR_CLIENT_SECRET	Programmatic / advanced use

The server checks for SENSR_ORG_TOKEN first, then SENSR_API_KEY as a fallback. If neither is set, it tries OAuth2 client credentials.

OAuth2 Config (advanced)

{
  "mcpServers": {
    "sensorbio": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/GetSensr-io/sensorbio-mcp-server",
        "sensorbio-mcp-server"
      ],
      "env": {
        "SENSR_CLIENT_ID": "your-client-id",
        "SENSR_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

---

What You Can Ask

Once connected, your AI assistant has access to these tools:

Tool	What it does	Example question
list_users	List all users in your organization	"Show me all users"
get_user_ids	Get all user IDs	"How many users are in the org?"
get_user_by_email	Find a user by their email address	"Look up [email protected]"
get_user_profile	Get a specific user's full profile	"Show me Bryan's profile"
search_user	Search users by name or email	"Find users named Sarah"
get_sleep	Sleep data: duration, score, stages	"How did I sleep last week?"
get_scores	Recovery, sleep, and activity scores	"What's my recovery score today?"
get_activities	Workouts and activity sessions	"What workouts did I do this week?"
get_biometrics	Heart rate, HRV, SpO2, respiratory rate	"What's my resting heart rate?"
get_calories	Calorie burn details	"How many calories did I burn today?"
get_org_sleep_summary	Sleep overview across your whole org	"How did the team sleep last night?"
get_org_scores_summary	Score overview across your whole org	"Show me the team's recovery scores"
debug_request	Raw API request (for troubleshooting)	Usually not needed directly

Most tools support flexible date ranges. You can say things like "last 7 days", "March 1st to March 10th", or "yesterday" and the AI will figure out the right parameters.

---

Environment Variables

Variable	Required	Description
SENSR_ORG_TOKEN	*	Organization API token (recommended)
SENSR_API_KEY	*	Alias for SENSR_ORG_TOKEN
SENSR_CLIENT_ID	**	OAuth2 client ID
SENSR_CLIENT_SECRET	**	OAuth2 client secret
SENSR_SCOPE		OAuth2 scope (optional)
SENSR_BASE_URL		Override API base URL (default: https://api.sensorbio.com)
SENSR_TZ		Timezone for "today" calculations (default: America/Chicago)

* Set one of SENSR_ORG_TOKEN or SENSR_API_KEY for token auth. ** Set both for OAuth2 auth. Token auth takes precedence if both are configured.

---

Troubleshooting

"Server not connecting"

• Make sure uv is installed: run uv --version in your terminal
• Check that your config file path is correct (see table above)
• Make sure you restarted Claude Desktop after editing the config

"Authentication error" or "Invalid API Key"

• Double-check your token. Copy it fresh from the developer portal.
• Make sure there are no extra spaces or line breaks in the token
• Tokens can expire. Generate a new one if yours is old.

"No data showing"

• Your Sensor Bio device needs to have synced recently
• Check that the user ID exists in your organization
• Try asking for a specific date: "Show my sleep for March 10th"

"Tool not found"

• Make sure the MCP server name in your config is exactly sensorbio
• Check Claude Desktop's MCP tools list for connection status

---

Development

Want to contribute or run locally?

# Clone the repo
git clone https://github.com/GetSensr-io/sensorbio-mcp-server.git
cd sensorbio-mcp-server

# Install dependencies
uv sync --dev

# Run tests
uv run pytest -v

# Lint
uv run ruff check .

# Run the server locally
SENSR_ORG_TOKEN=your-token uvx --from . sensorbio-mcp-server

# Smoke test (needs a valid token)
SENSR_ORG_TOKEN=your-token uv run python scripts/smoke_test.py

---

License

MIT