Understanding Tesla WiFi Diagnostics and the Mercury Tool
Tesla vehicles have a built-in WiFi module that exposes diagnostic interfaces, and over the years a number of tools have been built to access them. Mercury is one of those projects. It's not magic. It's a command-line utility that connects to a Tesla over its local WiFi network and pulls data that's normally only available through internal service tools. People get excited about it because it can read DTC codes, pull drive unit data, check battery cell voltages, and in some cases flash software under the right conditions. There's a lot of confusion around what Mercury actually does and what it doesn't do. Let me clear up the basics first, then get into how it works in practice. Mercury is an open-source Python-based toolkit originally developed by Tesla owners who wanted a way to talk to their car's internal network without paying for a dealership visit. It communicates with the Tesla API on the vehicle's WiFi network. The car exposes a small web server when it's in "WiFi Diagnostics" mode, and Mercury talks to that server using authenticated requests.
The key thing people miss is that Mercury does not hack into the car. It uses the same diagnostic endpoints that Tesla's own service tools use, just through a consumer-accessible interface. The authentication is handled through your Tesla account credentials, which the tool asks for when you first connect. Once authenticated, it can query a lot of the same data that a service center sees.
How to Set It Up
You'll need Python 3.9 or later installed on your machine. Clone the Mercury repository from GitHub, then install the dependencies using pip. The main dependency is the tesla-api library, which handles the authentication handshake with Tesla's servers. Once installed, you connect to the car by enabling WiFi diagnostics on the vehicle. Go to the touchscreen settings, navigate to software, and hold down the "Scan QR Code" option on the bottom of the screen. This activates a hotspot on the car. Connect your computer to that hotspot, then run Mercury with the appropriate command. The authentication process redirects you through Tesla's login page. Enter your credentials, authorize the connection, and Mercury will store a session token for future use. This token typically lasts for several hours before expiring, so you don't need to re-authenticate every single time you run a query.
Get the Full Details
What You Can Actually Do With It
The most common use case is reading diagnostic trouble codes. Run the DTC query and you'll get a full list of active and historical codes, along with descriptions and severity levels. This is useful for anyone doing their own maintenance or troubleshooting an intermittent issue before deciding whether to visit a service center. Battery diagnostics is another big one. Mercury can pull per-cell voltage readings from the high-voltage battery pack. This gives you individual cell voltages, not just the pack-level average that the app shows. Over time, tracking these values can reveal cell imbalance issues that haven't triggered a warning light yet. Drive unit data is also accessible. Motor temperatures, inverter status, and power flow metrics are all queryable. If you're doing an EV swap or conversion project and need to understand how the original Tesla drive components behave under load, this data is genuinely useful.
Software flashing is possible but heavily restricted. Mercury can trigger a software update download and installation, but it cannot flash arbitrary firmware. The vehicle still validates signatures and requires a valid session from Tesla's servers. Don't believe anyone who claims you can roll back to an older software version or install custom firmware through Mercury. That's not how it works.
A Real Problem I Hit and How I Fixed It
I ran into an issue where Mercury would authenticate successfully but then return empty or garbled data when querying battery cell voltages. The car was a 2019 Model 3 Long Range with firmware version 2021.8.10. Every other query worked fine, but the battery report came back with null values for individual cells and generic error messages. The problem turned out to be related to how Mercury parsed the response from the vehicle's diagnostic server. The firmware update in question changed the JSON structure of the battery data slightly, and the parsing logic in the version of Mercury I was using hadn't been updated to match. The fix was straightforward: I updated Mercury to the latest commit from the repository, which included a patch for that firmware's response format. If you're hitting similar issues, checking the project's issue tracker and pull requests is usually faster than digging through the code yourself. Someone else has likely already encountered the same firmware mismatch.
Important Limitations and Where It Falls Apart
Mercury has real constraints that people gloss over in forum posts. The biggest one is that it only works when you're connected to the car's local WiFi network. You cannot query a Tesla over the internet using Mercury. The diagnostic endpoints are not exposed through Tesla's cloud API, so remote access requires a completely different approach and different tools. Another limitation is that not all vehicles support the same diagnostic features. Older Model S and Model X vehicles from before 2017 have a significantly reduced set of accessible endpoints. Some functions simply don't exist on those cars, no matter what tool you use. Mercury can only read what the vehicle's software chooses to expose. There's also the issue of session timeouts. If your connection drops while Mercury is pulling a large dataset, you may lose partial results. Battery cell data for a full pack can involve thousands of individual readings, and the transfer can take a minute or two on older hardware. Keep the connection stable during large queries.
Perhaps most importantly, using Mercury to access certain diagnostic functions may void elements of your vehicle's warranty or violate Tesla's terms of service. This isn't a threat, it's just a factual consideration. If you damage a component through improper flashing or modify calibration data, Tesla is not obligated to cover the repair. Proceed with appropriate caution.
Where to Get It
The official Mercury repository is hosted on GitHub under the username hydra-cars. The project is free and open source. There are also several community-maintained forks with additional features, though these tend to drift from the original codebase and may introduce compatibility issues. Stick with the main repository unless you have a specific reason to use a fork. If you're looking for a more polished alternative with a graphical interface, something likeTeslaFi might be more suitable for casual users. Mercury is aimed at people who are comfortable with the command line and don't mind troubleshooting issues as they arise. The tool works on Windows, macOS, and Linux. I've tested it on Ubuntu 22.04 and Windows 11 without issues. The only dependency you really need beyond Python is a stable WiFi connection to the vehicle, which means standing next to the car or being within range of its hotspot. Range is typically about 30 to 50 feet in ideal conditions, less if there are obstructions between your computer and the vehicle.
Bottom Line
Mercury is a legitimate tool for accessing Tesla diagnostics over WiFi. It's not a hacking tool, it's not a way to remotely control your car, and it won't replace professional service equipment. But for reading codes, monitoring battery health, and understanding drive train data, it does what it claims. The setup is simple, the data is accurate, and the community around it is active enough that bugs tend to get patched quickly. Just don't expect it to do things it was never designed to do.
