# InBiot MCP Server
A Model Context Protocol (MCP) server for [InBiot](https://www.inbiot.es/) air quality monitoring devices, with WELL Building Standard compliance analysis. Built with [FastMCP](https://github.com/jlowin/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](https://my.inbiot.es)
- OpenWeather API key (optional, for outdoor data) from [OpenWeather](https://openweathermap.org/api)
## Quick Start
### Easy Installation (Recommended)
```bash
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
```bash
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:
```bash
copy inbiot-config.example.yaml inbiot-config.yaml # Windows
cp inbiot-config.example.yaml inbiot-config.yaml # Linux/macOS
```
Edit `inbiot-config.yaml`:
```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](https://my.inbiot.es) ā Device Settings
> - **OpenWeather API Key**: [OpenWeather](https://openweathermap.org/api) (free tier available)
> - **Coordinates**: [LatLong.net](https://www.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):**
```json
{
"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):**
```json
{
"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):
```json
{
"mcpServers": {
"inbiot": {
"command": "python",
"args": ["${workspaceFolder}/server.py"]
}
}
}
```
Or with `uv`:
```json
{
"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`
```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
```bash
pytest tests/ -v
```
### Running the Server Manually
```bash
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](https://www.inbiot.es/) - Air quality monitoring devices
- [My inBiot Platform](https://my.inbiot.es) - Device management and API keys
- [FastMCP](https://github.com/jlowin/fastmcp) - MCP framework
- [WELL Building Standard](https://www.wellcertified.com/) - Building certification
- [Model Context Protocol](https://modelcontextprotocol.io/) - MCP specification
