Skip to main content
Glama
Sign In
sylvia-iot-mcp

sylvia-iot-mcp

by woofdogtw
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Remote

sylvia-iot-mcp

An MCP server that exposes sylvia-iot-core management APIs as tools for AI assistants (Claude, etc.).

Note: This project is a practice ground for AI-assisted development using Claude Code with a spec-driven workflow powered by OpenSpec.

Features

66 tools across 10 capability areas:

Category

Tools

Auth

auth_tokeninfo, user_get, user_update

OAuth2 Clients

client_create/count/list/get/update/delete

Units

unit_create/count/list/get/update/delete

Applications

application_create/count/list/get/update/delete/stats, application_send_dldata

Networks

network_create/count/list/get/update/delete/stats, network_send_uldata

Devices

device_create/count/list/get/update/delete, bulk and range create/delete

Device Routes

device_route_create/count/list/delete, bulk and range create/delete

Network Routes

network_route_create/count/list/delete

Downlink Buffer

dldata_buffer_count/list/delete

Data

application/network uplink/downlink data counts and lists, coremgr operation logs

Related MCP server: OpenAPI MCP Server

Requirements

  • Node.js >= 18

  • A running sylvia-iot-core instance

  • An OAuth2 client with client_credentials grant enabled

Setup

1. Create an OAuth2 client

The MCP server authenticates to sylvia-iot-core using the client_credentials grant. You need a private (confidential) client with this grant enabled.

If you have admin access, you can create one via the sylvia-iot-auth API or management UI.

2. Configure environment variables

Copy .env.example to .env and fill in your values:

cp .env.example .env
SYLVIA_IOT_AUTH_URL=http://your-host/auth
SYLVIA_IOT_COREMGR_URL=http://your-host/coremgr
SYLVIA_IOT_DATA_URL=http://your-host/data
SYLVIA_IOT_CLIENT_ID=your-client-id
SYLVIA_IOT_CLIENT_SECRET=your-client-secret

The URL defaults point to a local sylvia-iot-core instance started with default settings.

3. Run the server

npm install
node src/index.js

Claude Code / Claude Desktop Integration

Add the server to your MCP config (e.g. ~/.claude.json for Claude Code).

Via npx (no installation required):

{
  "mcpServers": {
    "sylvia-iot": {
      "command": "npx",
      "args": ["-y", "github:woofdogtw/sylvia-iot-mcp"],
      "env": {
        "SYLVIA_IOT_AUTH_URL": "http://your-host/auth",
        "SYLVIA_IOT_COREMGR_URL": "http://your-host/coremgr",
        "SYLVIA_IOT_DATA_URL": "http://your-host/data",
        "SYLVIA_IOT_CLIENT_ID": "your-client-id",
        "SYLVIA_IOT_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

Via local checkout:

{
  "mcpServers": {
    "sylvia-iot": {
      "command": "node",
      "args": ["/path/to/sylvia-iot-mcp/src/index.js"],
      "env": {
        "SYLVIA_IOT_AUTH_URL": "http://your-host/auth",
        "SYLVIA_IOT_COREMGR_URL": "http://your-host/coremgr",
        "SYLVIA_IOT_DATA_URL": "http://your-host/data",
        "SYLVIA_IOT_CLIENT_ID": "your-client-id",
        "SYLVIA_IOT_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

Once connected, you can manage your IoT platform conversationally:

"List all units", "Create a new application for unit X", "Show me the latest uplink data from network Y"

Authentication

The server uses OAuth2 client_credentials grant to obtain a bearer token. The token is cached in memory and refreshed automatically on expiry or 401 responses. No user login is required.

Development

# Watch mode
npm run dev

# Run end-to-end tests (requires running sylvia-iot-core)
node test-mcp.mjs

Available Tools

66 tools
application_countA

Get the count of applications in a unit.

Inputs: unit (required), contains.

application_createA

Create an application. Returns applicationId and the one-time default password.

Inputs: code (required), unitId (required), hostUri (required), ttl, +3 more.

application_deleteA

Delete an application and all its resources.

Inputs: applicationId (required).

application_getB

Get details of a specific application.

Inputs: applicationId (required).

application_listB

List applications in a unit.

Inputs: unit (required), sort, limit, offset, +1 more.

application_send_dldataA

Send downlink data to a device via an application.

Inputs: payload (required), deviceId (required), applicationId (required).

application_statsA

Get queue statistics for an application (uldata, dldataResp, dldataResult queues).

Inputs: applicationId (required).

application_updateB

Update an application. password is required when changing hostUri.

Inputs: applicationId (required), ttl, info, name, +3 more.

auth_tokeninfoA

Get information about the current access token (userId, account, name, roles, clientId, scopes).

Inputs: no named parameters.

client_countA

Get the count of OAuth2 clients owned by the current user.

Inputs: no named parameters.

client_createA

Create an OAuth2 client. Use credentials:true to create a private client with a secret.

Inputs: name (required), scopes (required), redirectUris (required), image, +1 more.

client_deleteB

Delete an OAuth2 client.

Inputs: clientId (required).

client_getA

Get details of a specific OAuth2 client, including its secret if private.

Inputs: clientId (required).

client_listA

List OAuth2 clients owned by the current user.

Inputs: sort, limit, offset.

client_updateB

Update an OAuth2 client. Provide at least one field to change.

Inputs: clientId (required), name, image, scopes, +2 more.

data_application_dldata_countB

Get the count of application downlink data records.

Inputs: unit (required), addr, tend, device, +4 more.

data_application_dldata_listC

List application downlink data records.

Inputs: unit (required), addr, sort, tend, +7 more.

data_application_uldata_countB

Get the count of application uplink data records.

Inputs: unit (required), addr, tend, device, +4 more.

data_application_uldata_listC

List application uplink data records.

Inputs: unit (required), addr, sort, tend, +7 more.

data_coremgr_opdata_countA

Get the count of coremgr operation log records. Normal users see only their own logs.

Inputs: tend, tfield, tstart.

data_coremgr_opdata_listA

List coremgr operation log records. Normal users see only their own logs.

Inputs: sort, tend, limit, offset, +2 more.

data_network_dldata_countB

Get the count of network downlink data records.

Inputs: unit (required), addr, tend, device, +4 more.

data_network_dldata_listC

List network downlink data records.

Inputs: unit (required), addr, sort, tend, +7 more.

data_network_uldata_countC

Get the count of network uplink data records.

Inputs: unit (required), addr, tend, device, +4 more.

data_network_uldata_listC

List network uplink data records.

Inputs: unit (required), addr, sort, tend, +7 more.

device_bulk_createA

Bulk create devices by address list (max 1024). Existing addresses are skipped.

Inputs: unitId (required), networkId (required), networkAddrs (required), profile.

device_bulk_deleteA

Bulk delete devices by address list (max 1024).

Inputs: unitId (required), networkId (required), networkAddrs (required).

device_countA

Get the count of devices in a unit.

Inputs: unit (required), addr, network, profile, +1 more.

device_createA

Create a single device.

Inputs: unitId (required), networkId (required), networkAddr (required), info, +2 more.

device_deleteB

Delete a device and all its resources.

Inputs: deviceId (required).

device_getB

Get details of a specific device.

Inputs: deviceId (required).

device_listB

List devices in a unit.

Inputs: unit (required), addr, sort, limit, +4 more.

device_range_createA

Bulk create devices by hex address range (max 1024). startAddr and endAddr must be same-length hex strings.

Inputs: unitId (required), endAddr (required), networkId (required), startAddr (required), +1 more.

device_range_deleteB

Bulk delete devices by hex address range (max 1024).

Inputs: unitId (required), endAddr (required), networkId (required), startAddr (required).

device_route_bulk_createA

Bulk create device routes by address list (max 1024). Existing routes are skipped.

Inputs: networkId (required), networkAddrs (required), applicationId (required).

device_route_bulk_deleteB

Bulk delete device routes by address list (max 1024).

Inputs: networkId (required), networkAddrs (required), applicationId (required).

device_route_countB

Get the count of device routes in a unit.

Inputs: unit (required), device, network, application.

device_route_createB

Create a device route linking a device to an application. Both must belong to the same unit.

Inputs: deviceId (required), applicationId (required).

device_route_deleteC

Delete a device route.

Inputs: routeId (required).

device_route_listB

List device routes in a unit.

Inputs: unit (required), sort, limit, device, +3 more.

device_route_range_createA

Bulk create device routes by hex address range (max 1024). Existing routes are skipped. startAddr and endAddr must be same-length hex strings.

Inputs: endAddr (required), networkId (required), startAddr (required), applicationId (required).

device_route_range_deleteB

Bulk delete device routes by hex address range (max 1024).

Inputs: endAddr (required), networkId (required), startAddr (required), applicationId (required).

device_updateC

Update a device.

Inputs: deviceId (required), info, name, profile, +2 more.

dldata_buffer_countA

Get the count of buffered downlink data items waiting to be sent to devices.

Inputs: unit (required), device, network, application.

dldata_buffer_deleteC

Delete a buffered downlink data item.

Inputs: dataId (required).

dldata_buffer_listA

List buffered downlink data items waiting to be sent to devices.

Inputs: unit (required), sort, limit, device, +3 more.

network_countC

Get the count of networks in a unit.

Inputs: unit (required), contains.

network_createA

Create a network. Returns networkId and the one-time default password.

Inputs: code (required), unitId (required), hostUri (required), ttl, +3 more.

network_deleteA

Delete a network and all its resources.

Inputs: networkId (required).

network_getB

Get details of a specific network.

Inputs: networkId (required).

network_listC

List networks in a unit.

Inputs: unit (required), sort, limit, offset, +1 more.

network_route_countC

Get the count of network routes in a unit.

Inputs: unit (required), network, application.

network_route_createA

Create a network route linking a network to an application. All uplink data from the network will be forwarded to the application.

Inputs: networkId (required), applicationId (required).

network_route_deleteC

Delete a network route.

Inputs: routeId (required).

network_route_listC

List network routes in a unit.

Inputs: unit (required), sort, limit, offset, +2 more.

network_send_uldataB

Simulate uplink data from a device via a network.

Inputs: payload (required), deviceId (required), networkId (required).

network_statsB

Get queue statistics for a network (dldata queue).

Inputs: networkId (required).

network_updateC

Update a network. password is required when changing hostUri.

Inputs: networkId (required), ttl, info, name, +3 more.

unit_countA

Get the count of units owned by the current user.

Inputs: contains.

unit_createA

Create a unit. The calling user becomes the owner.

Inputs: code (required), info, name.

unit_deleteA

Delete a unit and all its resources.

Inputs: unitId (required).

unit_getA

Get details of a specific unit.

Inputs: unitId (required).

unit_listA

List units owned by the current user.

Inputs: sort, limit, offset, contains.

unit_updateC

Update a unit's display name or info.

Inputs: unitId (required), info, name.

user_getA

Get the current user's profile (account, name, info, roles, createdAt, modifiedAt, verifiedAt).

Inputs: no named parameters.

user_updateA

Update the current user's profile. Provide at least one of: password, name, info.

Inputs: info, name, password.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    B3.2/5.0

    Scored across 66 tools

    Disambiguation5/5

    Each tool targets a distinct resource-action pair, such as user, client, unit, application, network, device, routes, buffers, and data records. Even with 66 tools, the resource prefix clearly separates concerns and prevents misselection.

    Naming Consistency4/5

    Tool names consistently follow a snake_case resource_action pattern (e.g., client_create, device_list, network_route_delete). A few outliers like auth_tokeninfo and data_coremgr_opdata_list are slightly less verb-driven but remain predictable within their context.

    Tool Count2/5

    66 tools is far above the typical well-scoped range and will burden an agent with a large surface to navigate. While the platform covers many entities, the count is excessive and could likely be consolidated.

    Completeness4/5

    The toolset provides thorough CRUD coverage across users, clients, units, applications, networks, devices, routes, and data buffers, plus logging and data queries. Minor gaps exist, such as no network_route_get or update operation, but these are not critical to core workflows.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Resources

    Related MCP Connectors

    Related MCP Servers