# fiware-orion-mcp

MCP (Model Context Protocol) server for **FIWARE Orion Context Broker**. Enables LLMs like Claude to manage NGSI-v2 context entities — IoT devices, cameras, sensors, vehicles, and any real-world object modeled as a digital twin.

> No official FIWARE MCP exists yet. This is the first one.

## What is FIWARE Orion?

[FIWARE](https://www.fiware.org) is an open standard (ETSI NGSI-LD) for Smart City and IoT data management. The **Orion Context Broker** is its core component — it stores the current state of all entities and notifies subscribers when things change.

## Tools available

| Tool | Description |
|------|-------------|
| `orion_get_version` | Verify Orion connectivity and version |
| `orion_list_types` | List all entity types and their attributes |
| `orion_query_entities` | Query entities by type, pattern, filter, geo |
| `orion_get_entity` | Get full details of a specific entity |
| `orion_create_entity` | Create a new NGSI entity |
| `orion_update_attributes` | Update entity attributes |
| `orion_delete_entity` | Delete an entity |
| `orion_create_subscription` | Subscribe to attribute change notifications |
| `orion_list_subscriptions` | List active subscriptions |
| `quantumleap_get_history` | Get time-series history for an entity |
| `quantumleap_get_type_history` | Get aggregated history across entity type |

## Quick start

### 1. Start FIWARE stack (Docker)

```bash
cd docker
docker compose up -d
# Verify:
curl http://localhost:1026/version
curl http://localhost:8668/version
```

### 2. Install MCP server

```bash
pip install fiware-orion-mcp
# or from source:
pip install -e .
```

### 3. Configure Claude Code

Add to your `~/.claude/mcp.json` or project MCP config:

```json
{
  "mcpServers": {
    "fiware-orion": {
      "command": "python",
      "args": ["-m", "fiware_mcp.server"],
      "env": {
        "ORION_URL": "http://your-orion-host:1026",
        "QUANTUMLEAP_URL": "http://your-ql-host:8668"
      }
    }
  }
}
```

### 4. Environment variables

| Variable | Default | Description |
|----------|---------|-------------|
| `ORION_URL` | `http://localhost:1026` | Orion Context Broker URL |
| `QUANTUMLEAP_URL` | `http://localhost:8668` | QuantumLeap URL |
| `FIWARE_SERVICE` | _(empty)_ | Multi-tenancy service name |
| `FIWARE_SERVICE_PATH` | `/` | Multi-tenancy service path |

## Example session with Claude

```
> List all entity types in the Context Broker
> Show me all Camera entities that are offline
> Get the full details of Camera:TIMONE-01
> Update Camera:TIMONE-01 status to "maintenance"
> Show me the uptime history of Camera:TIMONE-01 for the last 7 days
```

## Roadmap

- [ ] NGSI-LD support (Orion-LD)
- [ ] Batch operations
- [ ] Geo-query helpers (find entities near a point)
- [ ] Export entities as GeoJSON

## License

MIT — contributions welcome.