Back to Browse

Gear MCP Server

Developer ToolsModerate7.6MCP RegistryLocal
Free

Server data from the Official MCP Registry

Read-only MCP access to Cloud Studio Gear IoT: sites, devices, live values, history and alarms.

About

Read-only MCP access to Cloud Studio Gear IoT: sites, devices, live values, history and alarms.

Security Report

7.6
Moderate7.6Low Risk

The Gear MCP server is a read-only client for the Cloud Studio Gear IoT API that requires a user access token, which is passed as a bearer token or obtained by login from environment variables, and it uses only network access to the configured Gear URL. No malicious patterns, shell execution, or hardcoded secrets were found; the only minor concerns are generic error handling and the HTTP transport relying on the caller to deploy behind HTTPS. Permissions match the server's stated purpose of reading IoT account data. Supply chain analysis found 1 known vulnerability in dependencies (0 critical, 1 high severity). Package verification found 1 issue.

7 files analyzed · 6 issues found

Security scores are indicators to help you make informed decisions, not guarantees. Always review permissions before connecting any MCP server.

Permissions Required

This plugin requests these system permissions. Most are normal for its category.

HTTP Network Access

Connects to external APIs or services over the internet.

env_vars

Check that this permission is expected for this type of plugin.

system_info

Check that this permission is expected for this type of plugin.

What You'll Need

Set these up before or after installing:

URL of your Gear instance, e.g. https://gear.cloud.studioOptional

Environment variable: GEAR_URL

Gear access token of the user the assistant acts asRequired

Environment variable: GEAR_TOKEN

How to Install

Add this to your MCP configuration file:

{
  "mcpServers": {
    "gear-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@cloudstudioiot/gear-mcp@0.1.0"
      ],
      "env": {
        "GEAR_URL": "your-gear-url-here",
        "GEAR_TOKEN": "your-gear-token-here"
      }
    }
  }
}

Some servers take additional arguments. See the repository for details.

Documentation

View on GitHub

From the project's GitHub README.

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

ToolWhat it answers
list_facilitiesWhich sites do I have?
list_devicesWhich devices are in this site, and which are offline, silent or alarmed? (only_problems)
get_deviceWhat is this device reading right now? Values with units, battery, open alarms, time of last data.
get_endpoint_historyHow did this temperature change between two dates? Points plus min, max and average, up to 5,000.
list_alarmsOpen, closed or all alarms of a client, site, device or endpoint.
find_devicesWhere 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.

Reviews

No reviews yet

Be the first to review this server!