Enables coding agents to reverse engineer and control Bluetooth LE and Classic gadgets by analyzing vendor app protocols and logs.
Also known as k0nnect/harald
- Stars
- 1
- Tools
- 18
- Downloads, 30 days
- —
- Latest version
- 0.2.2
- Last commit
- Nov 2, 2026
- License
- MIT
What is harald MCP?
harald enables coding agents to reverse engineer and control Bluetooth LE and Classic gadgets by analyzing vendor app protocols and logs. It exposes 18 tools, such as scan, connect, read_char.
Summary generated from the project's README
About harald MCP server
Reverse engineering Bluetooth LE and Classic gadgets to create custom drivers is what harald enables for developers using coding agents. By analyzing vendor application protocols and communication logs, an agent can learn the specific language, keys, and checksums required to control hardware directly without the original manufacturer's app. This process works with tools like Claude Code, Codex, and Cursor through a specialized MCP setup.
Users interact with the system by providing Bluetooth logs from an iPhone or Android device and, if necessary, the vendor's Android APK for analysis. The server provides tools to scan for nearby LE devices, connect to services, read or write characteristics, and search APK files for UUIDs. For Bluetooth Classic, it includes commands to list paired devices, manage RFCOMM services, and send or listen to byte streams. To ensure safety, all write operations require a manual arming command in the terminal to grant a specific budget of writes for a set duration.
What you can do with it
- 1Reverse engineer a gadget protocolAn agent can analyze a phone's Bluetooth log and a vendor's Android app to figure out how to communicate with a device.
- 2Control Bluetooth Classic hardwareA developer can instruct an agent to toggle features like noise cancelling on Sony headphones using Bluetooth Classic.
- 3Create standalone device driversThe system helps generate a standalone driver script and a small CLI so you can operate hardware without the vendor app.
- 4Analyze vendor application internalsYou can use the server to search through an Android APK to find specific Bluetooth UUIDs and encryption keys.
Written from the project's README. Every use case is checked against a quote from it.
How to install harald MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall harald MCP in Claude Code
$ claude mcp add harald -- uvx harald mcpInstall harald MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"harald": {
"command": "uvx",
"args": [
"harald",
"mcp"
]
}
}
}Install harald MCP in VS Code
.vscode/mcp.json
{
"servers": {
"harald": {
"type": "stdio",
"command": "uvx",
"args": [
"harald",
"mcp"
]
}
}
}Install harald MCP in VS Code CLI
$ code --add-mcp '{"name":"harald","type":"stdio","command":"uvx","args":["harald","mcp"]}'Install harald MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"harald": {
"command": "uvx",
"args": [
"harald",
"mcp"
]
}
}
}Install harald MCP in Codex
$ codex mcp add harald -- uvx harald mcpInstall harald MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.harald] command = "uvx" args = ["harald", "mcp"]
Install harald MCP in Gemini CLI
$ gemini mcp add -s user harald uvx -- harald mcpInstall harald MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"harald": {
"command": "uvx",
"args": [
"harald",
"mcp"
]
}
}
}Started by HostedMCP on 16 Nov 2026
We ran this command for harald 0.2.2 in an isolated container with no network and no keys. It answered and listed 18 tools.
harald MCP tools 18
Read from the server with tools/listscanscan for bluetooth le devices for `timeout` seconds, strongest signal first. manufacturer_data maps each company id (as 0x-hex) to its payload hex.
connectconnect to a device and list its gatt services and their characteristics. use the characteristic uuids listed here with read_char, write_char and subscribe.
read_charread a characteristic once; returns its value as hex.
write_charwrite hex bytes to a characteristic; returns the writes left. refused unless the human armed this device by running `harald arm <address>` in their own terminal. each write spends one from that budget, and firmware-update services stay blocked. by default it writes without response when the characteristic allows that, and with response otherwise. response=true waits for the device to acknowledge the write; false does not.
subscribecollect notifications from a characteristic for `seconds`. returns one entry per notification: seconds since the start and the value as hex.
open_captureshow the att and rfcomm timeline of a phone capture (.pklg or btsnoop log). one line per event with time, acl connection, direction, op and value hex. att events show their handle and uuid; rfcomm events (rfcomm data, rfcomm_open and rfcomm_close) show their server channel, e.g. ch=9. any warnings come first and a `showing a–b of n events` footer comes last. a capture can hold several connections, each with its own handles. page with limit and offset. handle (an integer, e.g. 18 for h=0x0012) keeps only att events on that handle, channel (e.g. 9) only rfcomm events on that channel, conn (e.g. 64 for c=0x0040) only events on that connection, and offset then counts those filtered events. for a bluetooth classic gadget, capture its android app in a btsnoop log: an iphone app reaches classic gadgets only through apple iap2, which harald shows as rfcomm data but can't unwrap yet. relative paths resolve against the server's working directory.
diffcompare hex payloads byte by byte. returns how many payloads have each length, the byte at every position that is the same in all of them (over the shortest), the positions that vary, and whether the set looks like block-cipher output.
guess_checksname the checksums and length fields one hex payload is consistent with. checks sum8 and xor8 in the last byte, and the byte before a trailing end marker, over the bytes after a leading start marker; crc16-ccitt in the last two; and a length byte at position 0 or 1.
try_keysdecrypt hex payloads with each candidate aes key, in ecb and in cbc with a zero iv, best-scoring first. samples holds the first plaintexts as hex. the score only tells keys apart across several distinct payloads: with one payload, or identical copies, every key scores 1.0. keys that are not 16, 24 or 32 bytes and payloads that are not a multiple of 16 bytes are skipped.
analyze_apkstatically analyze a vendor android app (.apk, .xapk or .apks) already on disk. detects the framework. for a native app it runs jadx and lists the uuids (gatt and rfcomm) in gatt_uuids and file:line candidates (uuids, aes keys, base64 blobs, command builders, rfcomm socket calls) to open under jadx_dir, the app's own package first and third-party libraries skipped. each list keeps at most 50 per kind; totals has the full counts, and when anything was cut a warning names the file under jadx_dir that lists them all. flutter and react-native apps keep their ble code compiled, so the warnings point to capture analysis instead. harald never downloads apps.
list_deviceslist the gadgets in harald's device library, with status and summary.
load_devicethe device library entry for one slug, including any app-wide key and cipher.
Show all 18 toolsShow fewer tools
read_notesthe working notes for a device, or an empty string when there are none. notes live in harald-work/<slug>/notes.md, relative to the server's working directory.
save_noteappend a timestamped note to harald-work/<slug>/notes.md. the path is relative to the server's working directory. slugs use lowercase letters, digits and hyphens, e.g. demo-lamp.
classic_deviceslist the bluetooth classic devices paired with this computer. connected says whether each is linked to this computer now. use an address from here with classic_services, classic_send and classic_listen.
classic_serviceslist a paired classic device's service records from this computer's cache. each record has a name, service-class uuids and an rfcomm channel (null when rfcomm cannot reach it). protected channels are standard profiles such as hands-free and headset, which harald never opens; firmware_update channels stay blocked for writes. refresh=true asks the device again instead of trusting the cache.
classic_sendsend hex messages to a classic device's rfcomm channel and collect its answers. refused unless the human armed this device by running `harald arm <address>` in their own terminal. each message spends one armed write, a query included, because classic has no read. all messages go over one connection, in order, with `listen` seconds (at most 30) of listening after each, so handshakes and acks can be sent as messages. service is an rfcomm service uuid or channel number from classic_services; standard profiles and channels missing from classic_services are refused, and firmware-update channels stay blocked. received holds each chunk with the message number it followed (0 = before the first), seconds since the channel opened and the value as hex. stopped explains a budget that ran out partway, or a link that failed after the first message; it is empty when every message was sent.
classic_listenopen a classic device's rfcomm channel, send nothing, and collect `seconds` (at most 30) of what it says. needs no arm, but standard profiles are still refused. service is an rfcomm service uuid or channel number from classic_services. returns one entry per chunk: seconds since the channel opened and the value as hex.
Automated checks
Ran Nov 14, 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 reachablek0nnect/harald is public and reachablegithub.com/k0nnect/harald ↗Pass
- Package names this repository as its sourceharald names k0nnect/harald as sourcepypi.org/project/harald/ ↗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-02github.com/k0nnect/harald ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from haraldPass
- No critical advisory in the package or its dependencies31 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHub
fig. 1 · claude + harald find a sony wh-1000xm5's control channel over bluetooth classic, wait for you to arm it, then turn noise cancelling on. real hardware, sped up.
一 how it works
harald is an mcp server, a cli and a playbook for coding agents. it gives your agent hands and ears for bluetooth le and classic, so it can work out the protocol of a gadget you own. then you control that gadget from your own code instead of the vendor's app.
| listen | decode | speak |
|---|---|---|
| harald reads what the vendor app says to the gadget, from your phone's bluetooth log. | your agent works out the language, keys and checksums included, by diffing payloads, testing keys and searching the vendor's android app. | you get the protocol written up and a standalone driver script with its own small cli. no vendor app. |
二 install
you need uv. then:
uv tool install harald
that puts harald on your path for the commands below. if your shell can't find it,
run uv tool update-shell. to try harald without installing it, run
uvx harald --help: uvx fetches harald and runs it once. tested on mac; linux is
experimental, see below.
the first time harald scans, macos asks whether your terminal app may use bluetooth. allow it. if you missed the prompt, turn it on in system settings › privacy & security › bluetooth.
two optional tools, for the steps that need them:
brew install jadxlets harald read a vendor's android app.brew install libimobiledevicerecords your iphone's bluetooth log from the terminal.
harald also works without an agent:
harald scan list bluetooth le devices nearby
harald connect <address> list a device's services and characteristics
harald read <address> <char> read a characteristic once
harald write <address> <char> <hex> write bytes, once you have armed the device
harald capture open <file> show a phone capture as a timeline
harald apk <file> search a vendor android app for uuids and keys
harald devices list the device library
harald drive <slug> <command> run a library device's driver
harald --help lists the rest, and bluetooth classic has
the commands for classic gadgets.
linux (experimental)
harald works on linux too, for bluetooth le and classic, through bluez. you need bluez
5.50 or newer with bluetoothd running, and your user in the bluetooth group: log out
and back in after adding it. harald needs no root, and there is no permission prompt
as on macos, but it can't reach bluetooth from inside a sandbox such as snap or
flatpak. the install above works as it is, on uv's own python too. if harald says
bluetooth is off, run bluetoothctl power on, with rfkill unblock bluetooth first
if it is blocked, and check bluetoothd with systemctl status bluetooth.
pair a classic gadget in your own terminal, in this order:
bluetoothctl pairable on. without it, bluez makes a bond that is gone after the next disconnect.bluetoothctl scan on, until the gadget shows up.bluetoothctl pair <address>.bluetoothctl trust <address>.
if harald says the gadget has forgotten the pairing, run
bluetoothctl remove <address> and pair it again.
linux is experimental: tested against an emulated gadget, not yet on real hardware. if you run it on linux, tell us how it went in an issue.
三 devices
| device | what harald found | status |
|---|---|---|
| sony wh-1000xm5 headphones | noise cancelling, ambient and battery over bluetooth classic | decoded |
| your device | open a pull request with its device.toml, protocol.md and driver.py |
wanted |
each decoded device lives in
devices/ with its protocol
written up and a standalone driver. harald devices lists them, and
harald drive <slug> <command> runs one, for example harald drive <slug> on.
四 agent setup
add the mcp server to your agent, then install the playbook: the step-by-step method your agent follows to crack a gadget.
claude code, in your project folder:
claude mcp add harald -- uvx harald mcp
harald playbook install claude-code --dest .claude/skills/harald
use --dest ~/.claude/skills/harald to have the skill in every project.
codex
add this to ~/.codex/config.toml, or run codex mcp add harald -- uvx harald mcp:
[mcp_servers.harald]
command = "uvx"
args = ["harald", "mcp"]
then, in your project folder:
harald playbook install codex
this writes AGENTS.md. if your project already has one, harald leaves it alone; use
--dest ~/.codex to install it for every project instead.
cursor
add this to .cursor/mcp.json in your project, or to ~/.cursor/mcp.json for every
project:
{
"mcpServers": {
"harald": {
"command": "uvx",
"args": ["harald", "mcp"]
}
}
}
cursor has no playbook; it uses harald's tools directly.
then ask your agent to work out your gadget with harald. it will ask you for two things only you can do.
record your phone talking to the gadget. a computer cannot overhear phone-to-gadget traffic without extra hardware, so the log comes from your own iphone. a bluetooth classic gadget's log comes from an android phone instead; see bluetooth classic.
- on the iphone, install apple's bluetooth logging profile: "bluetooth for ios/ipados" on apple's profiles and logs page. it is free.
- connect the iphone to your mac by cable. open packetlogger, from apple's
additional tools for xcode, and choose
file › new ios trace. or, from the terminal:
idevicebtlogger capture.pklg, which records until you press ctrl-c. - in the vendor app, do one thing at a time, a few seconds apart, in the order your agent asks for.
- stop the trace, save the
.pklgfile and give your agent its path. to look at it yourself:harald capture open capture.pklg.
if packetlogger records nothing, remove the logging profile and install it again.
get the vendor's android app. if the commands look encrypted, your agent asks for
the apk of the vendor app you already use. you don't need an android phone, and
harald never downloads apps: download it yourself from
apkmirror, which verifies each app's signature, or with
apkeep (apkeep -a <package name> .). the package
name is the id= part of the app's play store address.
五 bluetooth classic
some gadgets, often headphones and speakers, are controlled over bluetooth classic instead of bluetooth le: the vendor app talks to an rfcomm channel, a plain byte stream. harald reaches those too, on a mac or linux; bluetooth le works as before.
pair the gadget first: on a mac in system settings > bluetooth, keeping it connected
there; on linux with bluetoothctl, as in install. harald doesn't
search for or pair classic gadgets, and harald scan only sees bluetooth le. classic
addresses look like aa:bb:cc:11:22:33.
harald classic devices list the gadgets paired with this computer
harald classic services <address> list a gadget's rfcomm services
harald classic send <address> <service> <hex> send messages, once you have armed it
harald classic listen <address> <service> show what a channel says, sending nothing
harald capture open <file> --channel n show one rfcomm channel of a capture
<service> is a service uuid or channel number from harald classic services; add
--refresh there when the list looks out of date. a mac reads that list from its
own cache; on linux harald asks the gadget itself, so the gadget has to be on and in
range. harald classic send takes one or more messages and sends them in order,
listening for replies after each one (--listen s, 2 seconds by default). if the
grant runs out or the link fails partway, it prints what it sent and received, says
why on stderr and exits 1. harald classic listen sends nothing and listens for
--seconds s (5 by default). either listens for at most 30 seconds at a time.
like harald write, harald classic send needs harald arm <address> first, and
every message spends one write from the grant, a query too. harald never opens the
channels of protected profiles such as hands-free or file transfer; see
safety. your agent gets the same four as mcp tools: classic_devices,
classic_services, classic_send and classic_listen. none of them arms.
classic captures come from android. an iphone capture of a classic gadget shows only apple's iap2 wrapper, which harald can't unwrap yet, so record the vendor app from an android phone's bluetooth log:
- turn on developer options (tap the build number seven times in the phone's about screen), then turn on the bluetooth hci snoop log in them, choosing enabled rather than filtered if it asks.
- with the vendor app closed, turn the phone's bluetooth off and on, so the log is running before the app opens its channel.
- in the vendor app, do one thing at a time, a few seconds apart, as your agent asks.
- with usb debugging on, run
adb bugreport. its zip holdsbtsnoop_hci.log; give your agent that file's path, or look at it yourself withharald capture open btsnoop_hci.log.
harald apk flags the rfcomm sockets and uuids in a vendor's android app as well as
its bluetooth le calls.
六 safety
harald is for gadgets you own: interoperability and research. don't use it on anyone else's devices.
-
writes need you. harald refuses every write until you run, in your own terminal:
harald arm <address> --writes n --minutes mthat grants a budget of n writes for m minutes (50 and 30 if you leave the flags out), and each write spends one. it shows the grant and waits for you to type
arm, and it refuses to run without a terminal.harald statusshows what is armed andharald disarm <address>revokes it. there is no mcp tool that arms. -
the gate has limits.
harald armstops casual or accidental arming by an agent, but it is not a sandbox. grants live in a file,~/.harald/arm.json, and any agent that can run arbitrary commands or write files on your machine could get around the gate. what keeps a cooperative agent out is the playbook's rule: it never runsharald arm,harald write,harald drive,harald classic sendor a driver from its own shell; you do. it sends classic messages only through itsclassic_sendtool. -
firmware updates are blocked. writes to firmware-update (dfu) services stay refused even when a device is armed, so a stray write cannot start a firmware update. only
--allow-dfuonharald armlifts that, and working out a protocol never needs it. harald also blocks the classic firmware-update channels it knows, so far airoha's tooling channel, the same way unless you arm with--allow-dfu. but many classic gadgets take firmware over their normal control channel, where harald can't tell an update from any other message, so your agent must never send a message whose purpose it doesn't know. -
classic channels are fenced. harald never opens a channel whose service record lists hands-free, headset, dial-up networking, obex object push and file transfer, phonebook, messages, sim access or apple iap2. the serial port profile is allowed, since many gadgets' control channels use it. harald also refuses channels missing from the device's service list. with
harald classic send, every message spends one write, a query too. -
library drivers need no arming.
harald driveruns adevices/entry's standalone driver, which you start yourself, so it sits outside the gate. read a driver before you run it, as you would any script. -
only app-wide keys are shared. a
devices/entry may carry a key only if it is the same on every unit and ships inside the vendor app. per-unit keys and pairing keys never go in the library; they stay in your ownharald-work/folder.
七 contributing a device
cracked a gadget? your agent's work is in harald-work/<slug>/. turn it into
devices/<slug>/ with a device.toml, protocol.md and driver.py, then open a pull
request. the
contributing guide
has the details, including the keys rule.
mit license. harald is named after king harald "bluetooth" of denmark, after whom bluetooth is named; ᚼᛅᚱᛅᛚᛏᚱ is his name as it is carved on the jelling stone.
harald MCP questions
How do I add harald MCP to Claude Code?
Run claude mcp add harald -- uvx harald mcp in your terminal. Add --scope user to make it available in every project.
How do I add harald 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 harald MCP provide?
It exposes 18 tools, including scan, connect, read_char, write_char, subscribe.
Can harald control Bluetooth Classic devices?
Yes, it supports Bluetooth Classic on macOS and Linux, allowing agents to interact with RFCOMM channels used by devices like headphones and speakers.