This guide connects an AI client to your Thinger.io account through the MCP server of the thinger CLI. At the end, the agent lists your devices.

Today you connect through the CLI

The MCP server runs on your computer with the thinger CLI, and works with any Thinger.io server: the free Cloud account or a private instance. Your AI client starts it with the command thinger mcp.

Before you start

• A Thinger.io account. Your server is YOUR_SERVER: iot.thinger.io on the free Cloud account, or your own domain on a private instance.
• Node.js 20 or later. Check it with node --version.
• An MCP client: Claude Code, Claude Desktop, Cursor or any other client that runs local (stdio) MCP servers.

Steps

1. Install the CLI

   npm install -g @thinger-io/cli

   Check that it works:

   thinger --version

2. Sign in

   thinger login

   The command asks for the sign-in method and the server, and stores the session in a profile:

   Method	What happens
   Username and password	The CLI creates an access token named Thinger CLI in your account, with full access, and keeps it. thinger logout revokes it.
   Token	You paste an access token you created in Access Tokens. The agent gets only its permissions: see Permissions.
   OAuth	The CLI opens the browser to sign in. It needs an OAuth2 client registered on the server (--client-id); Thinger.io servers do not include one by default.

   To sign in without questions, for example with a restricted token:

   thinger login --server YOUR_SERVER --username YOUR_USER --token YOUR_TOKEN

   Here YOUR_TOKEN is an access token of your account. A bare host means HTTPS; for plain HTTP or a custom port, give the full URL (http://YOUR_SERVER:8080).

3. Add the MCP server to your client

   Claude Code

   claude mcp add thinger -- thinger mcp

   This adds the server to the current project, only for you. Add --scope user to make it available in all your projects, or --scope project to share it with the project in a .mcp.json file:

   claude mcp add --scope user thinger -- thinger mcp

   Claude Desktop

   In Claude Desktop, open Settings > Developer and click Edit Config. It opens claude_desktop_config.json, in ~/Library/Application Support/Claude/ on macOS and in %APPDATA%\Claude\ on Windows. Add the server under mcpServers:

   claude_desktop_config.json

   {
     "mcpServers": {
       "thinger": {
         "command": "thinger",
         "args": ["mcp"]
       }
     }
   }

   Save the file, then quit Claude Desktop completely and open it again.

   If the server does not start, Settings > Developer shows the error and a View logs button. On macOS the log is ~/Library/Logs/Claude/mcp-server-thinger.log.

   VS Code

   In VS Code, run MCP: Add Server from the Command Palette, or create .vscode/mcp.json in your project. VS Code lists its servers under servers, not mcpServers:

   .vscode/mcp.json

   {
     "servers": {
       "thinger": {
         "type": "stdio",
         "command": "thinger",
         "args": ["mcp"]
       }
     }
   }

   Other clients

   Any client that runs local MCP servers takes the same definition: the command thinger with the argument mcp. Cursor (~/.cursor/mcp.json, or .cursor/mcp.json in a project) and Windsurf (~/.codeium/windsurf/mcp_config.json) read it in this form:

   {
     "mcpServers": {
       "thinger": {
         "command": "thinger",
         "args": ["mcp"]
       }
     }
   }

   Codex reads it from ~/.codex/config.toml:

   config.toml

   [mcp_servers.thinger]
   command = "thinger"
   args = ["mcp"]

   For any other client, check in its documentation where it keeps its MCP servers.

   Without installing the CLI

   In Claude Code or a CI job you can run the CLI with npx instead of installing it:

   claude mcp add thinger -- npx -y @thinger-io/cli mcp

   Desktop apps are more fragile with npx: every start goes through npm and its cache, the first start is slow and needs the network, the version changes on its own, and on Windows the client needs "command": "cmd" with "args": ["/c", "npx", "-y", "@thinger-io/cli", "mcp"]. In Claude Desktop, VS Code, Cursor and other clients, install the CLI and use the thinger command.

4. Check the connection

   Open a new conversation and ask:

   Ask your AI agent

   List the devices of my Thinger.io account and tell me which ones are connected.

   The agent calls thinger_resource_list and answers with your devices. In Claude Code, /mcp shows the server as connected.

Result

The agent lists the devices of your account, with the permissions of the token of your profile. Every MCP tool is available to it.

Use several servers or accounts

A profile is one server and one account, with its credentials. The first profile you create is the default, and the MCP server uses it.

thinger profile add staging --no-activate
thinger profile list
thinger profile use staging

• thinger profile add signs in to another server or account and saves it as a new profile. The new profile becomes the default unless you pass --no-activate.
• thinger profile use changes the default profile. The MCP server uses the new default from the next tool call.
• The agent can use another profile for a single call: every tool takes a profile parameter, and thinger_profile_list lists the profiles. Ask, for example:

Ask your AI agent

Compare the devices of my staging profile with the ones of my default profile and tell me which ones are missing in staging.

To start the MCP server with another profile, set THINGER_PROFILE in the definition of the server. In Claude Code:

claude mcp add thinger-staging -e THINGER_PROFILE=staging -- thinger mcp

Another account on the same server is not a profile: an administrator reaches it with the user parameter. See Permissions.

Use environment variables in CI

Without a saved profile, for example in a CI job, set THINGER_SERVER and THINGER_TOKEN. They work for every command and for the MCP server:

THINGER_SERVER=YOUR_SERVER THINGER_TOKEN=YOUR_TOKEN thinger mcp

• THINGER_TOKEN is an access token; THINGER_SERVER is its server, a host or a full URL. Set both: a token without a server is an error.
• They take the place of the default profile, but not of a profile you name with --profile or THINGER_PROFILE.
• While THINGER_TOKEN is set, thinger login warns you that the variable overrides the profile you sign in to.

Keep the token in the secrets of your CI system, never in the repository.

Troubleshooting

Symptom	Cause	Fix
The client cannot start the server	The client does not find thinger or npx on its path, which happens often with desktop apps.	Use the full path of the command (which thinger on macOS and Linux, where thinger on Windows), or install Node.js 20 or later.
The client cannot start the server and its log shows npm error EACCES with a path under ~/.npm/_cacache	The npm cache has files owned by root, usually from an earlier sudo npm install. npx cannot use it.	Give the cache back to your user with sudo chown -R $(id -u):$(id -g) ~/.npm, or install the CLI (npm install -g @thinger-io/cli) and use "command": "thinger".
Every tool fails with not_configured	There is no profile.	Run thinger login.
Every tool fails with unauthorized and an HTTP 401	The token of the profile expired or was revoked.	Run thinger login again.
A tool fails with unauthorized and Forbidden (HTTP 403)	The token is valid but has no permission for that action. Signing in again does not change it.	Add the permission to the token in Access Tokens, or sign in with a token that has it.
The server is not reachable because of its certificate	The server uses a self-signed certificate.	Self-signed certificates are accepted for localhost. For other hosts, set THINGER_INSECURE=1 in the definition of the server, only on test servers.

Next steps

PermissionsWhat an AI agent is allowed to do in your Thinger.io account, how to limit it with an access token, and how to use it safely.MCP toolsEvery tool the Thinger.io MCP server offers to AI agents, with its parameters, and every resource type the agents can reach.Build dashboards with AIAsk an AI agent to create a dashboard app on the Dashboard SDK, develop it against your real data and publish it.CLIEvery command and option of the thinger CLI, plus how to install it, sign in, use profiles, script it with JSON output and run its MCP server.