Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@OpenEcoBee MCP Set the downstairs thermostat to 68°F for two hours"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
An open-source MCP server for controlling ecobee thermostats from ChatGPT. The Cloudflare deployment is designed to run entirely in the cloud: people connect their own ecobee account through a browser, without installing a local companion or obtaining an ecobee developer API key.
Experimental. The Cloudflare deployment, GitHub sign-in, ecobee login, restoring an encrypted session, and a real thermostat read through ChatGPT have been verified. Live temperature and HVAC changes have not been tested. Ecobee can block cloud browsers, and portal changes can break this unofficial integration.
The operator's hosted pilot is currently restricted to the operator's GitHub account. Other users can deploy their own instance using the guide below.
People do not need an ecobee developer application or manually copied access token. They still sign in to their own ecobee account and complete its normal multifactor authentication. The service saves the resulting browser session so later MCP calls can use it. This is authenticated access, with token handling kept out of the user's setup.
For the hosted service, users sign in with GitHub to identify their OpenEcoBee account and authorize the MCP connection. Ecobee login happens separately in a hosted browser. The operator hosting OpenEcoBee is trusted with the ecobee session: saved state is encrypted, but the running service has the key needed to decrypt it. See security.
Ecobee's standard portal sign-in requests thermostat access, profile read/write access, and sign-in grant management. OpenEcoBee exposes only its fixed thermostat tools, but the saved portal session has these broader permissions.
Ecobee currently does not accept new developer registrations, so this project uses its signed-in web portal instead of requiring a developer API key.
Related MCP server: Nature Remo MCP Server
The operator deploys the Worker and configures GitHub OAuth once. End users do not need Cloudflare accounts, server keys, or a process running on their computer.
Deploy the service using the Cloudflare guide.
Open the deployed /app page and sign in with GitHub.
Connect ecobee, complete the normal login/MFA in the hosted browser, and finish the connection.
Keep access read-only initially; enable thermostat changes in the account page when ready.
Add the deployed HTTPS /mcp endpoint to ChatGPT with OAuth. See Connect ChatGPT.
The deployment starts with a closed user allowlist. Verify login, account isolation, and a deliberate thermostat command before broadening access.
Tool | Purpose |
| List accessible thermostats and their identifiers. |
| Read temperature, humidity, mode, connection state, and setpoints. |
| Set a temporary heating/cooling hold; accepts Fahrenheit or Celsius. |
| Select |
| End a hold and resume the thermostat's schedule. |
Changes require writes to be enabled. Holds last 1–24 hours; setpoints must fit the thermostat's reported limits and minimum heat/cool separation. A response distinguishes accepted delivery from observed readback. Always check a pending result before retrying a change. Schedule resumption is reported as accepted without claiming physical verification.
Example prompts:
“List my thermostats and show the downstairs temperature.”
“Set the downstairs heating setpoint to 68°F and cooling setpoint to 76°F for two hours.”
“Resume the downstairs thermostat's schedule.”
Use Node.js 22 or newer:
npm install
npm run check
npm test
npm run buildTry the simulated thermostat without an account:
npm run demo
# To exercise changes against the simulation:
node dist/cli.js serve --demo --allow-writesThe demo is a stdio MCP server and waits for a client. For a local real-account experiment, install Chromium and complete ecobee login on this computer:
npx playwright install chromium
node dist/cli.js login
node dist/cli.js status
node dist/cli.js serve
# Explicitly opt in to thermostat changes:
node dist/cli.js serve --allow-writesLocal state defaults to .openecobee/profile, relative to the working directory. Use --profile /absolute/path/to/profile or OPENECOBEE_PROFILE when a client launches the server from a different directory. Treat the directory as credentials and run only one process against it at a time.
A generic local MCP client can launch the server with:
{
"mcpServers": {
"openecobee": {
"command": "node",
"args": [
"/absolute/path/to/OpenEcoBee/dist/cli.js",
"serve",
"--profile",
"/absolute/path/to/OpenEcoBee/.openecobee/profile"
]
}
}
}For local HTTP, run node dist/cli.js serve --transport http. It listens at http://127.0.0.1:3000/mcp, with local host/origin checks. This local endpoint has no OAuth and must remain private. The hosted Worker has a separate authenticated deployment path.
The browser integration depends on ecobee portal internals. Login sessions can expire, cloud browsers can be rejected, and the adapter can stop working after a portal release. There is no offline control path.
See architecture, CONTRIBUTING.md, and SECURITY.md. This is an independent MIT-licensed implementation inspired by emrikol/ecobee-mcp; its code is not copied. REA is a reference for investigating browser applications, not a runtime dependency.
Not affiliated with or endorsed by ecobee, OpenAI, GitHub, or Cloudflare.
Read a thermostat's current status. All fields ending F are Fahrenheit.
| Name | Required | Description | Default |
|---|---|---|---|
| thermostat_id | Yes | Exact thermostat id returned by list_thermostats. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the useful output convention that fields ending F are Fahrenheit, but does not disclose rate limits, auth needs, or details of the returned status fields. With annotations covering behavior, this is a modest but real addition.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences: the purpose is front-loaded, and the Fahrenheit note is a compact, relevant follow-up. There is no filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple, the required id is fully documented in the schema, and annotations cover safety. Since no output schema exists, the description partially compensates with the Fahrenheit unit convention, though it still does not enumerate the returned status fields. That gap keeps it from a 5.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the single parameter thermostat_id is already documented as the exact id returned by list_thermostats. The description adds no further parameter meaning. Baseline 3 is appropriate when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'Read a thermostat's current status.' This clearly distinguishes it from mutation-oriented siblings like set_temperature and set_hvac_mode. It does not explicitly differentiate from list_thermostats, so a 4 rather than a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states what the tool does but gives no guidance on when to use it versus alternatives such as list_thermostats or the setter tools. There are no exclusions or prerequisites. Usage is only implied by the tool name and purpose.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List thermostats and their current temperatures, setpoints, limits, and connection state.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnly, idempotent, non-destructive, and open-world behavior, so the safety profile is covered. The description earns credit by enumerating the returned fields (temperatures, setpoints, limits, connection state), which matters since there is no output schema. It omits pagination, auth, and rate-limit behavior, but those are secondary here.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with the verb first and no filler. Every clause (returned fields) carries information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a no-param, no-output-schema read tool, the description covers purpose and return fields, which is most of what an agent needs. Explicit differentiation from get_thermostat_status and any result-size/pagination caveat would make it fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a parameterless tool is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description pairs a specific verb ('List') with the resource ('thermostats') and enumerates the data returned. It reads clearly enough to distinguish a bulk-enumeration tool from the singular 'get_thermostat_status', though it never explicitly contrasts the two siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is only implied by the plural 'List' verb — there is no explicit statement of when to call this versus get_thermostat_status or any other sibling. No prerequisites or exclusions are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Resume the thermostat's programmed schedule from a hold. Requires account write permission and the client write scope when hosted, or server --allow-writes locally.
| Name | Required | Description | Default |
|---|---|---|---|
| thermostat_id | Yes | Exact thermostat id returned by list_thermostats. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, idempotentHint=false and openWorldHint=true, so the description earns credit mainly by adding the auth prerequisites: account write permission plus the client write scope when hosted, or server --allow-writes locally. It does not, however, explain what the destructive behavior actually is (whether the current hold/setpoint is discarded), which is the one trait an agent would most want clarified.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the action and state transition, with the precondition sentence following. No redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter mutation with annotations and no output schema, the definition covers purpose, state transition and auth requirements adequately. The remaining gap is the effect on existing device state, which matters given the destructive hint but is not described.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There is a single parameter and schema description coverage is 100%, with the schema itself explaining that thermostat_id is the exact id from list_thermostats. The description adds no parameter-level detail, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (resume), the exact resource (the thermostat's programmed schedule), and the originating state (from a hold). This is clearly distinguishable from the sibling actions set_temperature and set_hvac_mode, which override rather than restore the program.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'from a hold' implies the condition under which this tool applies, but no alternative is named and no explicit when-not guidance is given (e.g. do not call after set_temperature has already overridden the program). Usage is inferable rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Change thermostat HVAC mode to off, heat, cool, or auto. Requires account write permission and the client write scope when hosted, or server --allow-writes locally.
| Name | Required | Description | Default |
|---|---|---|---|
| mode | Yes | ||
| thermostat_id | Yes | Exact thermostat id returned by list_thermostats. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the safety profile is covered. The description adds genuinely new context by spelling out the two authentication paths required to complete the write, which the annotations cannot express. It stops short of explaining reversibility or effects on the running schedule.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, zero filler, with the action and its allowed values front-loaded before the permission requirements. Every clause carries information the agent needs.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter mutation tool whose annotations already disclose the destructive/non-idempotent profile, the description covers the action, the value set, and the auth gate. Nothing critical is missing, though a note about interaction with an active schedule or the effect on temperature setpoints would round it out.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50%: thermostat_id is documented in the schema while mode is defined only by its enum. The description restates the enum values, which duplicates the schema rather than adding format or constraint detail, so the baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (Change) and resource (thermostat HVAC mode) and enumerates the exact resulting states (off, heat, cool, auto). An agent can distinguish this from set_temperature and resume_schedule without opening any schema, since the mode-setting action is uniquely named.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description supplies prerequisites (account write permission, client write scope, or --allow-writes locally) but never says when to choose this over set_temperature or resume_schedule. Usage is implied by the enumerated modes rather than stated as guidance, so it sits at the minimum-viable level.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set a 1–24 hour temperature hold. Supply heat, cool, or both with explicit F/C units. Keeps any omitted setpoint. Requires account write permission and the client write scope when hosted, or server --allow-writes locally.
| Name | Required | Description | Default |
|---|---|---|---|
| cool | No | ||
| heat | No | ||
| unit | Yes | ||
| hours | Yes | ||
| thermostat_id | Yes | Exact thermostat id returned by list_thermostats. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructive=true, openWorldHint=true, and non-idempotent. The description goes beyond them by disclosing the partial-update behavior (omitted setpoints are kept) and the exact authorization requirements for hosted vs local use, which is genuinely useful context for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tight sentences: purpose and scope first, then parameter behavior, then permissions. No filler, and the most important constraint (the 1–24 hour hold) is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a write tool, the description pairs annotations (destructive, open-world) with authorization requirements, expiry semantics, and partial-update behavior. No output schema exists, but that is acceptable for a setter; the only gap is the absence of alternative-tool routing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 20% (just thermostat_id), so the description must compensate, and it does: it explains that heat/cool may be supplied singly or together, that units must be explicit F/C, and that omitted setpoints persist. It still does not fully enumerate all five parameters, so it is not exhaustive.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource plus a scoping constraint ('Set a 1–24 hour temperature hold'), which clearly separates it from set_hvac_mode and resume_schedule. It never names a sibling explicitly, so it falls short of the 'distinguishes from siblings' bar for a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives concrete operating conditions ('Supply heat, cool, or both with explicit F/C units. Keeps any omitted setpoint') and prerequisites (account write permission, client write scope, or --allow-writes locally). It does not state when NOT to use this versus resume_schedule or set_hvac_mode, so no exclusions or alternative routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0get_thermostat_statuslist_thermostatsresume_scheduleset_hvac_modeset_temperatureScored across 5 tools
list_thermostats and get_thermostat_status both read thermostat state and their boundaries blur, since list_thermostats already returns temperatures and setpoints. However, the plural listing vs. single-thermostat detail distinction and the write actions (set_temperature, set_hvac_mode, resume_schedule) are otherwise clearly separable.
All tools follow a clean snake_case verb_noun pattern: list_thermostats, get_thermostat_status, set_temperature, set_hvac_mode, resume_schedule. Verbs are consistently action-oriented and nouns are clear.
Five tools is well-scoped for a thermostat controller: discovery, status read, temperature hold, mode change, and schedule resume. Each tool earns its place with no filler.
The surface covers the core read/set/resume lifecycle of thermostat control, but lacks operations like viewing the programmed schedule, setting fan/humidity modes, or canceling a hold explicitly. Minor gaps an agent can mostly work around.
Control your Tesla from your AI assistant - climate, charging, access, and security.
Lets Claude, ChatGPT, and Muse read and update your beckett tasks, notes, calendar, and lists.
Connect your Oura Ring account and enable access to your wellness data in apps and automations. In…
Connects ChatGPT to your Apple Calendar via a local Mac agent + Vercel relay