InBiot MCP Server

A Model Context Protocol (MCP) server for InBiot air quality monitoring devices, with WELL Building Standard compliance analysis. Built with FastMCP.

Features

Core Capabilities

• Real-time Air Quality Monitoring - Get latest measurements from InBiot MICA sensors
• Historical Data Retrieval - Access measurements between specific dates with statistical analysis
• WELL Building Standard Compliance - Assess air quality against WELL v2, ASHRAE 62.1/55, and WHO Indoor standards
• Outdoor Context - Compare indoor conditions with outdoor weather and air quality (via OpenWeather)
• Health Recommendations - Generate actionable advice based on current conditions
• Data Authenticity - All responses include mandatory provenance tracking (no simulated data)

Advanced Features

• Modular Skills Architecture - Organized into monitoring, analytics, compliance, and weather skills for easy maintenance
• YAML/JSON Configuration - Easy device management with config files (backward compatible with .env)
• Automatic Retries - Exponential backoff for transient API failures and rate limits
• Data Export - Export historical data to CSV/JSON formats with optional time aggregation
• Statistical Analysis - Comprehensive statistics (min/max/mean/median/std dev/quartiles) and trend detection
• Feature-Level WELL Compliance - Detailed breakdown by WELL v2 features (A01-A08, T01-T07) with specific mitigation strategies

Prerequisites

• Python 3.10 or higher
• InBiot MICA device(s) with API access from My inBiot
• OpenWeather API key (optional, for outdoor data) from OpenWeather

Quick Start

Easy Installation (Recommended)

git clone https://github.com/miguel-escribano/inBiot_MCP_with_WeatherAPI_and_WELL_standard.git
cd inBiot_MCP_with_WeatherAPI_and_WELL_standard

# Run interactive setup
python setup.py

The setup script will:

• Check Python version
• Install dependencies (automatically tries uv, falls back to pip)
• Create configuration template
• Optionally run tests

Manual Installation

1. Clone and Install

git clone https://github.com/miguel-escribano/inBiot_MCP_with_WeatherAPI_and_WELL_standard.git
cd inBiot_MCP_with_WeatherAPI_and_WELL_standard

# Install with uv (recommended)
uv sync

# Or with pip
pip install -e .

2. Configure Your Devices

Create inbiot-config.yaml from the example:

copy inbiot-config.example.yaml inbiot-config.yaml   # Windows
cp inbiot-config.example.yaml inbiot-config.yaml     # Linux/macOS

Edit inbiot-config.yaml:

openweather_api_key: "your-key-here"  # Optional

devices:
  office:  # Device ID (any name you want)
    name: "Main Office"
    api_key: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
    system_id: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
    latitude: 40.416775
    longitude: -3.703790

  lab:  # Add more devices as needed
    name: "Laboratory"
    api_key: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
    system_id: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
    latitude: 40.416775
    longitude: -3.703790

Where to find your credentials:

• InBiot API Key & System ID: My inBiot Platform → Device Settings
• OpenWeather API Key: OpenWeather (free tier available)
• Coordinates: LatLong.net or Google Maps

Note: JSON and environment variable configurations are also supported for backward compatibility. See the code for details.

MCP Client Configuration

Claude Desktop

Add to claude_desktop_config.json:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

Recommended (no manual dependency installation needed):

{
  "mcpServers": {
    "inbiot-well": {
      "command": "uvx",
      "args": [
        "--from",
        "/ABSOLUTE/PATH/TO/InBiot_MCP",
        "inbiot-mcp-server"
      ]
    }
  }
}

This uses uvx to automatically manage dependencies in an isolated environment.

Alternative (requires pip install -e . first):

{
  "mcpServers": {
    "inbiot-well": {
      "command": "python",
      "args": ["/ABSOLUTE/PATH/TO/InBiot_MCP/server.py"]
    }
  }
}

Cursor IDE

Create .cursor/mcp.json in your project root (project-specific) or ~/.cursor/mcp.json (global):

{
  "mcpServers": {
    "inbiot": {
      "command": "python",
      "args": ["${workspaceFolder}/server.py"]
    }
  }
}

Or with uv:

{
  "mcpServers": {
    "inbiot": {
      "command": "uv",
      "args": ["--directory", "/ABSOLUTE/PATH/TO/inbiot-mcp", "run", "python", "server.py"]
    }
  }
}

VS Code with Cline Extension

Add to Cline's MCP settings:

macOS: ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
Windows: %APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json

{
  "mcpServers": {
    "inbiot": {
      "command": "python",
      "args": ["/ABSOLUTE/PATH/TO/inbiot-mcp/server.py"]
    }
  }
}

Important Notes:

• Replace /ABSOLUTE/PATH/TO/inbiot-mcp with the actual absolute path to your installation
• Restart your IDE/application after configuration changes
• Check MCP logs: Open Output panel (Cmd+Shift+U) → Select "MCP Logs"

Usage Examples

For AI Assistants (Cursor, Claude, etc.)

Use these prompts to interact with the InBiot MCP server:

Basic Air Quality Check

Show me the current air quality readings from all InBiot devices

WELL Compliance Analysis

Check WELL Building Standard compliance for the Main Office device and 
provide detailed recommendations for any parameters that don't meet the standards

Indoor vs Outdoor Comparison

Compare the indoor air quality at the Laboratory with current outdoor conditions 
and explain any significant differences

Historical Analysis

Get historical data for the Main Office device from 2024-01-01 to 2024-01-31
and analyze trends in CO2 and PM2.5 levels

Statistical Analysis (NEW)

Get comprehensive statistics for the office device from 2024-01-01 to 2024-01-31
including min, max, mean, median, standard deviation, and trend analysis

Data Export (NEW)

Export historical data from the office device for January 2024 to CSV format
with daily aggregation for external analysis

Feature-Level WELL Compliance (NEW)

Show me the detailed WELL Building Standard compliance breakdown by feature
(A01-A08 for air quality, T01-T07 for thermal comfort) for the Main Office device,
including specific mitigation strategies for any non-compliant features

Health Recommendations

Based on current readings from all devices, provide health and comfort
recommendations for occupants

Available Tools

Tool	Description	Parameters
list_devices	List all configured InBiot devices	None
get_latest_measurements	Get current readings from a device	device (string)
get_historical_data	Get measurements between dates with statistics	device, start_date, end_date (YYYY-MM-DD)
well_compliance_check	Assess WELL Standard compliance	device (string)
well_feature_compliance	NEW: Detailed WELL v2 feature breakdown (A01-A08, T01-T07)	device (string)
outdoor_snapshot	Get outdoor weather and air quality	device (string)
indoor_vs_outdoor	Compare indoor vs outdoor conditions	device (string)
health_recommendations	Generate health recommendations	device (string)
export_historical_data	NEW: Export historical data to CSV/JSON	device, start_date, end_date, format (csv/json), aggregation (none/hourly/daily/weekly)
get_data_statistics	NEW: Comprehensive statistical analysis with trends	device, start_date, end_date

Available Resources

URI	Description
inbiot://docs/parameters	Air quality parameters reference
inbiot://docs/well-standards	WELL Building Standard criteria
inbiot://docs/iaq	IAQ indicator guide
inbiot://docs/thermal-comfort	Thermal comfort guide
inbiot://docs/virus-resistance	Virus resistance indicator guide
inbiot://docs/ventilation	Ventilation efficiency guide

Available Prompts

Prompt	Description
air_quality_analysis	Comprehensive air quality analysis
compare_devices	Compare two devices
well_certification_analysis	WELL certification assessment
health_recommendations_prompt	Health recommendations

API Rate Limits & Resilience

• InBiot API: 6 requests per device per hour
• OpenWeather API: Depends on your subscription tier

Automatic Retry Handling:

• Exponential backoff for transient failures (network timeouts, 5xx errors)
• Respects 429 rate limit headers with proper retry timing
• Configurable retry attempts (default: 3) with increasing delays
• Maximum delay capped at 30 seconds to prevent excessive waits

WELL Building Standard

Assesses air quality against:

• WELL v2 - Features A01-A08 (Air) and T01-T07 (Thermal Comfort)
• ASHRAE 62.1 & 55 - Ventilation and thermal comfort standards
• WHO Indoor Air Quality Guidelines - Health-based thresholds

Certification levels: Platinum (90%+), Gold (75%+), Silver (60%+), Bronze (40%+)

Architecture

Modular Skills Design

The MCP server is organized into modular skills for better maintainability and scalability:

🔍 Monitoring Skill (src/skills/monitoring/)

• list_devices - List all configured devices
• get_latest_measurements - Real-time air quality data
• get_historical_data - Historical measurements with trends

📊 Analytics Skill (src/skills/analytics/)

• get_data_statistics - Comprehensive statistical analysis
• export_historical_data - CSV/JSON export with aggregation

✅ Compliance Skill (src/skills/compliance/)

• well_compliance_check - WELL Building Standard assessment
• well_feature_compliance - Feature-by-feature breakdown (A01-A08, T01-T07)
• health_recommendations - Actionable health advice

🌤️ Weather Skill (src/skills/weather/)

• outdoor_snapshot - Current outdoor conditions
• indoor_vs_outdoor - Indoor/outdoor comparison

Benefits:

• ✅ Easy to maintain - Each skill is self-contained
• ✅ Easy to extend - Add new skills without touching existing code
• ✅ Easy to test - Test skills independently
• ✅ Clear organization - Tools grouped by domain

Development

Running Tests

pytest tests/ -v

Running the Server Manually

python server.py
# or
uv run python server.py

Project Structure

inbiot-mcp/
├── server.py                      # Main FastMCP server (modular, uses skills)
├── setup.py                       # Easy setup script
├── inbiot-config.yaml             # YAML configuration (recommended)
├── inbiot-config.example.yaml    # YAML config template
├── src/
│   ├── skills/                    # Modular skills (NEW!)
│   │   ├── monitoring/            # Device monitoring tools
│   │   │   └── tools.py           # list_devices, get_latest, get_historical
│   │   ├── analytics/             # Data analysis tools
│   │   │   └── tools.py           # statistics, export
│   │   ├── compliance/            # WELL compliance tools
│   │   │   └── tools.py           # well_check, feature_compliance, recommendations
│   │   └── weather/               # Weather comparison tools
│   │       └── tools.py           # outdoor_snapshot, indoor_vs_outdoor
│   ├── api/                       # API clients (InBiot, OpenWeather)
│   │   ├── inbiot.py              # With retry logic
│   │   └── openweather.py         # With retry logic
│   ├── config/                    # Configuration management
│   │   ├── loader.py              # YAML/JSON/ENV config loader
│   │   └── validator.py           # Config validation
│   ├── models/                    # Pydantic schemas
│   │   └── schemas.py
│   ├── well/                      # WELL compliance engine
│   │   ├── compliance.py          # Assessment engine
│   │   ├── features.py            # WELL v2 feature definitions
│   │   └── thresholds.py          # WELL/ASHRAE/WHO thresholds
│   └── utils/                     # Utilities
│       ├── aggregation.py         # Statistical analysis
│       ├── exporters.py           # CSV/JSON exporters
│       ├── provenance.py          # Data authenticity tracking
│       └── retry.py               # Exponential backoff retry logic
├── resources/                     # Static documentation
└── tests/                         # Test suite

What's New (Recent Improvements)

Configuration Simplification

• YAML/JSON Config Files: Easier device management compared to environment variables
• Auto-detection: Loads YAML → JSON → ENV automatically (backward compatible)
• Validation: Warns about common issues (duplicate IDs, default coordinates)
• Easy Setup: Interactive setup.py script for guided installation

Enhanced Reliability

• Automatic Retries: Exponential backoff for transient failures
• Rate Limit Handling: Respects 429 Retry-After headers
• Better Error Messages: Context-rich error reporting with endpoint details
• Configurable: Customize retry attempts and delays

Data Export & Analysis

• CSV/JSON Export: Professional data export for external analysis
• Time Aggregation: Hourly, daily, or weekly data summarization
• Statistical Analysis: Min/max/mean/median/std dev/quartiles
• Trend Detection: Automatic trend identification (increasing/decreasing/stable)

Enhanced WELL Compliance

• Feature-Level Breakdown: Explicit A01-A08 (Air) and T01-T07 (Thermal) reporting
• Specific Mitigation Strategies: 5+ actionable strategies per feature
• Health Impact Details: Clear explanation of health implications
• Targeted Recommendations: Parameter and feature-specific advice

All improvements maintain full backward compatibility with existing configurations.

Troubleshooting

Server Not Connecting

1. Check the MCP logs in your IDE/application
2. Verify the absolute path in your configuration
3. Ensure configuration file exists (inbiot-config.yaml, inbiot-config.json, or .env)
4. Test manually: python server.py (should see FastMCP initialization)
5. Run setup: python setup.py for guided troubleshooting

API Rate Limit Errors

• InBiot API allows 6 requests per device per hour
• Server automatically retries with exponential backoff
• If you hit the limit, wait for the retry window or space out requests

Configuration Not Loading

• Check configuration priority: YAML → JSON → ENV
• Verify YAML/JSON syntax (use online validators if needed)
• Look for validation warnings on server startup
• Test config: python -c "from src.config.loader import ConfigLoader; print(ConfigLoader.load())"

Missing Outdoor Data

• Verify your OpenWeather API key in configuration
• Check that device coordinates are correct (not 0, 0)
• Free tier has usage limits

Dependency Installation Fails

• If running in active venv: deactivate first, then run python setup.py
• Try manual install: pip install fastmcp httpx pydantic python-dotenv pyyaml
• Windows permission errors: Run as administrator or use fresh venv

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT

Links

• InBiot - Air quality monitoring devices
• My inBiot Platform - Device management and API keys
• FastMCP - MCP framework
• WELL Building Standard - Building certification
• Model Context Protocol - MCP specification