Cloud Studio Gear

Gear MCP server

An MCP server for the Cloud Studio Gear IoT platform. It lets Claude, ChatGPT, Cursor, VS Code or any other MCP client read a Gear account: sites, devices and their status, live values, history and alarms. Ask "which freezers in the Madrid warehouse have been offline since yesterday?" and the assistant finds out on its own.

It only reads. No tool sends commands to devices or changes configuration, and every call to Gear carries the user's own access token, so the assistant sees exactly what that user sees in Gear and nothing else.

Tools

Tool	What it answers
list_facilities	Which sites do I have?
list_devices	Which devices are in this site, and which are offline, silent or alarmed? (only_problems)
get_device	What is this device reading right now? Values with units, battery, open alarms, time of last data.
get_endpoint_history	How did this temperature change between two dates? Points plus min, max and average, up to 5,000.
list_alarms	Open, closed or all alarms of a client, site, device or endpoint.
find_devices	Where is the device called "freezer 3", with address 70B3D57E… or serial SN-0042?

All six are marked read-only (readOnlyHint) for clients that ask before running a tool.

What you need

• Node.js 20 or newer.

• The URL of your Gear instance, for example https://gear.cloud.studio or your own domain.

• A Gear access token for the user the assistant will act as. Ask your Gear administrator for:

  • an application with these API permissions: Accounts.Login, Accounts.Read, Facilities.Read, Facilities.ReadAlarms, Devices.Read and Endpoints.Read (Manager → Global → Applications);
  • a user limited to the client the assistant should see. Every answer is filtered by this user's permissions, so a user who sees one client gives an assistant that sees one client.

  With both, get a token with AdminService.LoginWithExpiration or a persistent access token. The Gear API skill explains the login in detail.

Instead of a token you can give the server GEAR_APP_TOKEN, GEAR_EMAIL and GEAR_PASSWORD: it logs in at start with a token that lasts 12 hours. This does not work for users with two-factor authentication.

Install

The package runs with npx; there is nothing to install by hand.

Claude Code

claude mcp add gear \
  --env GEAR_URL=https://gear.example.com \
  --env GEAR_TOKEN=<access token> \
  -- npx -y @cloudstudioiot/gear-mcp

Claude Desktop

Settings → Developer → Edit Config, and add to claude_desktop_config.json:

{
  "mcpServers": {
    "gear": {
      "command": "npx",
      "args": ["-y", "@cloudstudioiot/gear-mcp"],
      "env": {
        "GEAR_URL": "https://gear.example.com",
        "GEAR_TOKEN": "<access token>"
      }
    }
  }
}

Restart Claude Desktop. The six tools appear under the tools icon.

Cursor

The same mcpServers block as Claude Desktop, in ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project).

VS Code

In .vscode/mcp.json. VS Code asks for the token once and keeps it out of the file:

{
  "inputs": [
    { "type": "promptString", "id": "gear-token", "description": "Gear access token", "password": true }
  ],
  "servers": {
    "gear": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cloudstudioiot/gear-mcp"],
      "env": { "GEAR_URL": "https://gear.example.com", "GEAR_TOKEN": "${input:gear-token}" }
    }
  }
}

Other clients

Any client that starts a local MCP server over stdio works: the command is npx -y @cloudstudioiot/gear-mcp with GEAR_URL and GEAR_TOKEN in its environment.

Running it as a remote server

The server also speaks Streamable HTTP, for a team that wants one shared server instead of one per laptop:

GEAR_URL=https://gear.example.com npx -y @cloudstudioiot/gear-mcp --http --port 3333 --host 127.0.0.1

• Endpoint POST /mcp; health check GET /health.
• Each request must carry the user's Gear token: Authorization: Bearer <access token>. Without it the answer is 401. The server is stateless: it keeps no sessions and no tokens, and each request runs with its own token, so two users on the same server never see each other's data.
• It listens on 127.0.0.1 by default. To expose it, put it behind HTTPS (a reverse proxy). Tokens must never travel in clear text.

Cloud Studio does not host a public instance of this server.

Good to know

• Times are UTC. Dates are accepted as 2026-10-01 or 2026-10-01T08:00:00Z.
• last_data_utc is the newest reading of any of the device's endpoints, or null if it never sent data.
• A battery's percentage is null when Gear has a voltage but no percentage for it; read voltage then. The server does not estimate one from the other.
• Gear returns at most 500 rows per API call. get_endpoint_history pages for you up to 5,000 points and sets truncated when there is more. list_devices counts up to 500 open alarms per site (open_alarms_capped), and find_devices searches up to 200 sites.
• Gear's errors come back as tool errors with Gear's code, for example Gear 8001: The access token is invalid or has expired, or Gear 8004 when the user has no access to what was asked.

Develop

git clone https://github.com/CloudStudioIoT/gear-mcp
cd gear-mcp
npm install
npm test          # 25 tests against recorded response shapes, no network
npm run build
GEAR_URL=... GEAR_TOKEN=... node dist/src/index.js

npm run test:isolation checks, against a real instance, that two users of different clients each see only their own data in all six tools, also when one passes the other's IDs by hand. It needs GEAR_URL, GEAR_TOKEN_A and GEAR_TOKEN_B, and only reads.

To build your own integration on the Gear API rather than through an assistant, see the Gear API skill and the API documentation.

Security

Report vulnerabilities as described in https://cloudstudioiot.com/.well-known/security.txt.

License

MIT © Cloud Studio IoT, S.L.