BodySpec MCP Server

A Model Context Protocol (MCP) server that provides tools for interacting with the BodySpec API, enabling access to DEXA scan data and health information.

Features

• Complete API Coverage: All BodySpec API endpoints are available as MCP tools
• Authentication: Bearer token authentication via .env file configuration
• Error Handling: Comprehensive error handling and logging
• Type Safety: Full Pydantic model validation
• Async Support: Built with async/await for optimal performance
• MCP Protocol: Proper stdio transport implementation for MCP communication

Available Tools

API Status

• bodyspec_api_info - Get API information and version
• bodyspec_health_check - Check API health status

User Management

• bodyspec_get_user_info - Get current user profile
• bodyspec_update_user_info - Update user profile information

Appointments

• bodyspec_list_appointments - List user appointments with filtering
• bodyspec_get_appointment - Get detailed appointment information

Results

• bodyspec_list_results - List user test results
• bodyspec_get_result_detail - Get detailed result information

DEXA Analysis

• bodyspec_dexa_scan_info - Get DEXA scan metadata
• bodyspec_dexa_composition - Get body composition data by region
• bodyspec_dexa_bone_density - Get bone mineral density measurements
• bodyspec_dexa_percentiles - Get age/gender-matched percentile rankings
• bodyspec_dexa_visceral_fat - Get visceral adipose tissue analysis

Installation

1. Clone or download this repository

2. Install dependencies:

   pip install -r requirements.txt

3. Set up authentication:

   Step 1: Get your Bearer token

   1. Visit the BodySpec API documentation at https://app.bodyspec.com/docs
   2. Log in to your BodySpec account (if not already logged in)
   3. Navigate to the Authentication or API Keys section in the documentation
   4. Look for instructions on generating or retrieving your OAuth2 access token (Bearer token)
   5. Copy the token - it should be a long string of characters (JWT format)

   Note: If you need help finding the token, check the MCP setup guide at https://app.bodyspec.com/#mcp-setup

   Step 2: Configure the token

   Create a .env file in the project root and add your token:

   # Copy the example file
   cp env_example.txt .env
   
   # Edit .env and add your token
   BODYSPEC_ACCESS_TOKEN=your_token_here

   You can also configure other settings in the .env file (see Configuration section below).

   Step 3: Configure mcp.json for Cursor

   Add the minimal configuration to your mcp.json file (required by Cursor):

   {
     "mcpServers": {
       "BodySpec": {
         "command": "python",
         "args": ["/path/to/bodyspec-mcp/server.py"],
         "env": {
           "PYTHONUNBUFFERED": "1"
         }
       }
     }
   }

   Note: The token and other configuration values should only be set in the .env file, not in mcp.json. The mcp.json file is only needed for Cursor to know how to run the server.

Authentication

The server uses Bearer token authentication. You need to obtain a JWT access token from BodySpec's API documentation and configure it as shown above.

Usage

Running the Server

python server.py

The server will start and be ready to accept MCP tool calls.

Example Tool Calls

Get API Information

{
  "name": "bodyspec_api_info",
  "arguments": {}
}

List Recent Appointments

{
  "name": "bodyspec_list_appointments",
  "arguments": {
    "limit": 10,
    "sort_order": "newest_first"
  }
}

Get Body Composition Data

{
  "name": "bodyspec_dexa_composition",
  "arguments": {
    "result_id": "your_result_id_here"
  }
}

Get Percentile Rankings

{
  "name": "bodyspec_dexa_percentiles",
  "arguments": {
    "result_id": "your_result_id_here",
    "min_age": 30,
    "max_age": 40
  }
}

Configuration

The server is configured using environment variables in the .env file. Configuration sources are loaded in the following order of precedence (highest to lowest):

1. .env file (highest precedence) - All configuration values should be set here
2. System environment variables - Variables set in your shell/system
3. mcp.json env section - Only used for Cursor-specific settings like PYTHONUNBUFFERED

Note: The .env file is where you should configure your token and all other settings. The mcp.json file is only needed for Cursor to know how to run the server and should contain minimal configuration.

Variable	Description	Default
BODYSPEC_ACCESS_TOKEN	Bearer token for API authentication	Required
BODYSPEC_BASE_URL	BodySpec API base URL	https://app.bodyspec.com
BODYSPEC_API_VERSION	API version	v1
BODYSPEC_TIMEOUT	Request timeout in seconds	30
BODYSPEC_MAX_RETRIES	Maximum retry attempts	3
BODYSPEC_LOG_LEVEL	Logging level	INFO

Data Models

The server uses Pydantic models that match the BodySpec API specification:

• UserResponse: User profile information
• Appointment: Appointment details with location and service info
• ResultSummary/ResultDetailResponse: Test result information
• DexaCompositionResponse: Body composition data by region
• DexaBoneDensityResponse: Bone density measurements
• DexaPercentilesResponse: Age/gender-matched percentile rankings
• DexaVisceralFatResponse: Visceral adipose tissue analysis

Error Handling

The server provides comprehensive error handling:

• Authentication Errors: Invalid or expired tokens
• API Errors: HTTP errors from the BodySpec API
• Validation Errors: Invalid input parameters
• Network Errors: Timeout and connection issues

All errors are logged and returned as user-friendly messages.

Development

Project Structure

bodyspec-mcp-server/
├── server.py              # Main MCP server
├── config.py              # Configuration management
├── auth.py                # Authentication handling
├── api_client.py          # BodySpec API client
├── models.py              # Pydantic data models
├── tools/                 # MCP tools directory
│   ├── __init__.py
│   ├── status_tools.py    # API status tools
│   ├── user_tools.py      # User management tools
│   ├── appointment_tools.py # Appointment tools
│   ├── result_tools.py    # Results tools
│   └── dexa_tools.py      # DEXA-specific tools
├── requirements.txt       # Python dependencies
├── README.md             # This file
└── example_usage.py      # Usage examples

Adding New Tools

1. Create a new tool module in the tools/ directory
2. Implement the register_*_tools() function
3. Import and register the tools in server.py

Testing

Test individual components:

# Test authentication
from auth import create_auth
auth = create_auth()
print(f"Authenticated: {auth.is_authenticated()}")

# Test API client
from api_client import create_client
import asyncio
client = create_client()
info = await client.get_api_info()
print(f"API Version: {info.version}")

Support

For issues with the BodySpec API, contact: [email protected]

For MCP server issues, check the logs (written to stderr) and ensure you have configured the BODYSPEC_ACCESS_TOKEN in your .env file.

License

This project is provided as-is for integrating with the BodySpec API. Please refer to BodySpec's terms of service for API usage guidelines.