InBiot MCP Server
A Model Context Protocol (MCP) server for InBiot air quality monitoring devices, with WELL Building Standard compliance analysis. Built with FastMCP.
Este MCP es la evolución del CustomGPT original: Anne - AAQ & IAQ & WELL AP Consultant
Cómo Usar
Hay dos opciones:
| Opción | Ventaja | Requisitos |
|---|---|---|
| A) Servidor remoto | Listo para usar, sin instalación | Node.js 18+ |
| B) Instalación local | Configura tus propios dispositivos | Python 3.10+, credenciales InBiot |
Opción A: Servidor Remoto (Demo)
Hay un servidor de demostración disponible en mcp.miguel-escribano.com. Requiere autenticación por token.
Seguridad
El servidor implementa:
- Autenticación por token (
X-MCP-Token) - Sin token válido = 401 Unauthorized - Sanitización de credenciales - API keys y system IDs nunca se exponen en respuestas
Configuración
Cursor - Añade esto a ~/.cursor/mcp.json (Windows: %USERPROFILE%\.cursor\mcp.json):
"inbiot": {
"command": "npx",
"args": ["-y", "mcp-remote", "https://mcp.miguel-escribano.com/inbiot/sse", "--header", "X-MCP-Token: TU_TOKEN"]
}
Claude Desktop - Añade esto a claude_desktop_config.json:
"inbiot": {
"command": "npx",
"args": ["-y", "mcp-remote", "https://mcp.miguel-escribano.com/inbiot/sse", "--header", "X-MCP-Token: TU_TOKEN"]
}
Nota: Contacta al administrador para obtener un token de acceso.
Dispositivos disponibles: cafeteria, main_office, laboratory, miguel_demo
Ejemplos de uso: Una vez conectado, prueba estas preguntas:
- "How can you help me? Explain your capabilities and available tools"
- "List available devices, then get latest measurements from main_office"
- "Compare indoor vs outdoor air quality for main_office at Pamplona, Spain"
- "WELL compliance check for laboratory with recommendations and provenance"
Opción B: Instalación Local
Si quieres configurar tus propios dispositivos InBiot, sigue las instrucciones de instalación más abajo.
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-mcpwith 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 devicesget_latest_measurements- Real-time air quality dataget_historical_data- Historical measurements with trends
📊 Analytics Skill (src/skills/analytics/)
get_data_statistics- Comprehensive statistical analysisexport_historical_data- CSV/JSON export with aggregation
✅ Compliance Skill (src/skills/compliance/)
well_compliance_check- WELL Building Standard assessmentwell_feature_compliance- Feature-by-feature breakdown (A01-A08, T01-T07)health_recommendations- Actionable health advice
🌤️ Weather Skill (src/skills/weather/)
outdoor_snapshot- Current outdoor conditionsindoor_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.pyscript 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
- Check the MCP logs in your IDE/application
- Verify the absolute path in your configuration
- Ensure configuration file exists (
inbiot-config.yaml,inbiot-config.json, or.env) - Test manually:
python server.py(should see FastMCP initialization) - Run setup:
python setup.pyfor 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