Allows AI clients to read IoT data including sites, devices, live values, history, and alarms from the Cloud Studio Gear platform.
Also known as CloudStudioIoT/gear-mcp, gear-mcp, @cloudstudioiot/gear-mcp
- Stars
- 0
- Tools
- 6
- Downloads, 30 days
- —
- Latest version
- 0.1.0
- Last commit
- Nov 13, 2026
- License
- MIT
What is Cloud Studio Gear MCP?
Cloud Studio Gear allows AI clients to read IoT data including sites, devices, live values, history, and alarms from the Cloud Studio Gear platform. It exposes 6 tools, such as list_facilities, list_devices, get_device.
Summary generated from the project's README
About Cloud Studio Gear MCP server
Monitoring IoT infrastructure through an AI assistant is what Cloud Studio Gear enables for users of Claude, ChatGPT, Cursor, and VS Code. This server provides a read-only connection to your Gear account, allowing an AI to inspect sites, devices, live sensor values, historical data, and active alarms. It functions as a local tool via stdio or as a remote server using Streamable HTTP, ensuring that the assistant only accesses information permitted by the specific user's access token.
To set it up, you provide your Gear instance URL and an access token or credentials via environment variables. The server uses six specific tools: list_facilities, list_devices, get_device, get_endpoint_history, list_alarms, and find_devices. Because it is strictly read-only, the assistant cannot change device configurations or send commands. It is designed for developers and operators who need to query complex telemetry, such as retrieving up to 5,000 historical data points or identifying offline hardware, using natural language instructions.
What you can do with it
- 1Identify offline hardwareAsk the assistant to find specific equipment that has lost connectivity within a particular location.
- 2Analyze sensor trendsRequest a summary of how a specific measurement has changed over a defined period.
- 3Locate specific devicesFind a piece of hardware using its name, serial number, or unique address.
- 4Check alarm statusRetrieve a list of active or historical alarms for a specific site or device.
Written from the project's README. Every use case is checked against a quote from it.
How to install Cloud Studio Gear MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Cloud Studio Gear MCP in Claude Code
$ claude mcp add --env 'GEAR_TOKEN=<YOUR_GEAR_TOKEN>' --env 'GEAR_URL=<GEAR_URL>' gear-mcp -- npx -y @cloudstudioiot/gear-mcpInstall Cloud Studio Gear MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"gear-mcp": {
"command": "npx",
"args": [
"-y",
"@cloudstudioiot/gear-mcp"
],
"env": {
"GEAR_TOKEN": "<YOUR_GEAR_TOKEN>",
"GEAR_URL": "<GEAR_URL>"
}
}
}
}Install Cloud Studio Gear MCP in VS Code
.vscode/mcp.json
{
"servers": {
"gear-mcp": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@cloudstudioiot/gear-mcp"
],
"env": {
"GEAR_TOKEN": "<YOUR_GEAR_TOKEN>",
"GEAR_URL": "<GEAR_URL>"
}
}
}
}Install Cloud Studio Gear MCP in VS Code CLI
$ code --add-mcp '{"name":"gear-mcp","type":"stdio","command":"npx","args":["-y","@cloudstudioiot/gear-mcp"],"env":{"GEAR_TOKEN":"<YOUR_GEAR_TOKEN>","GEAR_URL":"<GEAR_URL>"}}'Install Cloud Studio Gear MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"gear-mcp": {
"command": "npx",
"args": [
"-y",
"@cloudstudioiot/gear-mcp"
],
"env": {
"GEAR_TOKEN": "<YOUR_GEAR_TOKEN>",
"GEAR_URL": "<GEAR_URL>"
}
}
}
}Install Cloud Studio Gear MCP in Codex
$ codex mcp add gear-mcp --env 'GEAR_TOKEN=<YOUR_GEAR_TOKEN>' --env 'GEAR_URL=<GEAR_URL>' -- npx -y @cloudstudioiot/gear-mcpInstall Cloud Studio Gear MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.gear-mcp] command = "npx" args = ["-y", "@cloudstudioiot/gear-mcp"] [mcp_servers.gear-mcp.env] GEAR_TOKEN = "<YOUR_GEAR_TOKEN>" GEAR_URL = "<GEAR_URL>"
Install Cloud Studio Gear MCP in Gemini CLI
$ gemini mcp add -s user -e 'GEAR_TOKEN=<YOUR_GEAR_TOKEN>' -e 'GEAR_URL=<GEAR_URL>' gear-mcp npx -- -y @cloudstudioiot/gear-mcpInstall Cloud Studio Gear MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"gear-mcp": {
"command": "npx",
"args": [
"-y",
"@cloudstudioiot/gear-mcp"
],
"env": {
"GEAR_TOKEN": "<YOUR_GEAR_TOKEN>",
"GEAR_URL": "<GEAR_URL>"
}
}
}
}Needs a key before it starts
Started on 16 Nov 2026 with no keys, it stopped and asked for one, so a client sees no tools until you set the variables above.
Cloud Studio Gear MCP tools 6
Detected from the READMElist_facilitieslist_devicesget_deviceget_endpoint_historylist_alarmsfind_devices
Configuration
GEAR_TOKENRequiredSecretGear access token of the user the assistant acts as
GEAR_URLRequiredURL of your Gear instance, e.g. https://gear.cloud.studio
Automated checks
Ran Nov 13, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablecloudstudioiot/gear-mcp is public and reachablegithub.com/cloudstudioiot/gear-mcp ↗Pass
- Package names this repository as its source@cloudstudioiot/gear-mcp names cloudstudioiot/gear-mcp as sourcenpmjs.com/package/@cloudstudioiot/gear-mcp ↗Pass
- Build provenance (Sigstore attestation)No build attestation published for this releaseNot checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-12github.com/cloudstudioiot/gear-mcp ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from @cloudstudioiot/gear-mcpPass
- No critical advisory in the package or its dependenciesthe package checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model6 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubGear 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.studioor 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.LoginWithExpirationor 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 checkGET /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.1by 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-01or2026-10-01T08:00:00Z. last_data_utcis the newest reading of any of the device's endpoints, ornullif it never sent data.- A battery's
percentageisnullwhen Gear has a voltage but no percentage for it; readvoltagethen. The server does not estimate one from the other. - Gear returns at most 500 rows per API call.
get_endpoint_historypages for you up to 5,000 points and setstruncatedwhen there is more.list_devicescounts up to 500 open alarms per site (open_alarms_capped), andfind_devicessearches 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, orGear 8004when 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.
Cloud Studio Gear MCP questions
How do I add Cloud Studio Gear MCP to Claude Code?
Run claude mcp add --env 'GEAR_TOKEN=<YOUR_GEAR_TOKEN>' --env 'GEAR_URL=<GEAR_URL>' gear-mcp -- npx -y @cloudstudioiot/gear-mcp in your terminal. Add --scope user to make it available in every project.
How do I add Cloud Studio Gear MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does Cloud Studio Gear MCP provide?
It exposes 6 tools, including list_facilities, list_devices, get_device, get_endpoint_history, list_alarms.
Can this server change device configurations?
No, the server is read-only and does not send commands to devices or change any configurations.
How does the server handle user permissions?
Every call carries the user's own access token, ensuring the assistant only sees exactly what that specific user is authorized to see in Gear.
What are the requirements to run the server?
You need Node.js 20 or newer, your Gear instance URL, and a Gear access token.
Does it support two-factor authentication?
If you use the GEAR_EMAIL and GEAR_PASSWORD method for login, it will not work for users with two-factor authentication.