Ble MCP Server

Let AI agents interact with real BLE hardware — scan, connect, read, write, and subscribe.

Connector by es617 · GitHub account verified by the MCP Registry

IndexedMITLocal (stdio)Remote (HTTP)Remote (SSE)★ 18

Install

Works with Claude Code, Codex, VS Code, Cursor, Windsurf, Claude Desktop. Read the repository before you give any tool access to your data.

npx agentmarket install connector/es617-ble-mcp-server

Asks which of your tools to add it to (Claude Code, Codex, Cursor, VS Code, Windsurf, Gemini CLI, Claude Desktop) and shows the change first. See https://agentmart.dev/cli.

Get the weekly diff

The weekly diff: one email a week with new agent tools, notable updates and grade changes, plus security alerts for tools you follow. Double opt-in, one-click unsubscribe.

About

Let AI agents interact with real BLE hardware — scan, connect, read, write, and subscribe.

Reviews

Write a review

No reviews yet. Installed it? Reviews come from verified installers only. How reviews work

Permissions

What this server can do and what it asks for, from its tool list and install config. Checked Oct 25, 2026.

Tools: 20 read · 7 write · 0 delete · 8 not yet classified
Secrets: None asked for
Install scripts: Not scanned yet
Runs as: Python package

Tools by what they do 35

Read from the source code; the running server may list different tools.

Read 20 · Look things up without changing anything.

ble.connection_status
ble.connections.list
ble.discover
ble.mtu
ble.plugin.list
ble.plugin.template
ble.poll_notifications
ble.read
ble.read_descriptor
ble.scan_get_results
ble.scans.list
ble.spec.get

Show 8 more tools

ble.spec.list
ble.spec.read
ble.spec.search
ble.spec.template
ble.subscriptions.list
ble.tasks.list
ble.trace.status
ble.trace.tail

Write 7 · Create, change, send or run things.

ble.spec.attach
ble.spec.register
ble.subscribe
ble.tasks.cancel
ble.unsubscribe
ble.write
ble.write_descriptor

Not yet classified 8 · We could not tell from the name and description.

ble.connect
ble.disconnect
ble.drain_notifications
ble.plugin.load
ble.plugin.reload
ble.scan_start
ble.scan_stop
ble.wait_notification

Secrets and settings it asks for

Other settings (environment variables or headers).

BLE_MCP_ALLOW_WRITES
BLE_MCP_PLUGINS
BLE_MCP_TOOL_SEPARATOR
BLE_MCP_WRITE_ALLOWLIST

Files it touches

Any path the agent passes to its tools

Tools (35)

Read from the source code; the running server may differ. Descriptions are the server’s own words; hidden characters are shown as [U+…].

ble.connect
Connect to a BLE peripheral by address. Returns a connection_id, device identity (device_name, service_uuids from scan cache), and spec status (null if none attached). After connecting: 1) Use ble.spec.list to check for a matching protocol spec by device name or service UUIDs. If a match is found, attach it with ble.spec.attach. If no match, ask the user if they have a protocol spec for this device. 2) Use ble.plugin.list to check for a plugin whose name matches the device. If a matching plugin is loaded, its tools are available to use directly.
ble.connection_status
Check whether a connection is still alive. Returns connected (bool), address, and disconnect_ts if the device disconnected unexpectedly. Use this to verify a connection before a sequence of operations.
ble.connections.list
List all tracked connections with their status, address, name, timestamps, and subscription count. Useful for recovering connection IDs after context loss.
ble.disconnect
Disconnect a BLE peripheral by connection_id.
ble.discover
Discover services and characteristics on a connected device. Results are cached per connection.
ble.drain_notifications
Batch-collect notifications: waits up to timeout_s for the first notification, then keeps collecting until idle_timeout_s passes with no new data, max_items is reached, or the total timeout_s expires. Ideal for bursty flows like downloading a log file or dataset over BLE notifications.
ble.mtu
Return the negotiated MTU (Maximum Transmission Unit) for a connection. The effective max write payload per packet is mtu - 3 bytes (ATT header). Useful for determining chunk sizes for large writes.
ble.plugin.list
List loaded plugins with their tool names and metadata. Each plugin may include a 'meta' dict with matching hints like service_uuids, device_name_contains, or description — use these to determine which plugin fits the connected device. Also returns whether plugins are enabled and the current policy. Plugins require BLE_MCP_PLUGINS env var — set to 'all' for all or 'name1,name2' to allow specific plugins. If disabled, tell the user to set this variable when adding the MCP server.
ble.plugin.load
Load a new plugin from a file or directory path. Requires BLE_MCP_PLUGINS env var to be set.
ble.plugin.reload
Hot-reload a plugin by name. Re-imports the module and refreshes tools. Requires BLE_MCP_PLUGINS env var to be set.
ble.plugin.template
Return a Python plugin template. Use this when creating a new plugin. Optionally pre-fill with a device name. Save the result to .ble_mcp/plugins/<name>.py, fill in the tools and handlers, then load with ble.plugin.load.
ble.poll_notifications
Non-blocking: return up to max_items buffered notifications immediately. Returns an empty list if the queue is empty. Also returns a dropped counter showing how many notifications were lost to queue overflow since subscription start.
ble.read
Read the value of a GATT characteristic.
ble.read_descriptor
Read a GATT descriptor by handle. Use ble.discover to find descriptor handles. Descriptors provide metadata about characteristics (e.g. CCCD, user description).
ble.scan_get_results
Non-blocking: return the devices discovered so far by a running (or finished) scan. Also returns whether the scan is still active. Call this to check progress or to decide whether to stop early.

Show 20 more tools

ble.scan_start
Start a background BLE scan. Returns a scan_id immediately. The scan runs in the background for up to timeout_s seconds. Use ble.scan_get_results to check discovered devices and ble.scan_stop to end the scan early.
ble.scan_stop
Stop a running scan early and return the final list of discovered devices. Safe to call on an already-finished scan.
ble.scans.list
List all tracked scans with their status, filters, timestamps, and device count. Useful for recovering scan IDs after context loss.
ble.spec.attach
Attach a registered spec to a connection session (in-memory only). The spec will be available via ble.spec.get for the duration of this connection. After attaching, check ble.plugin.list for a matching plugin, then present the user with their options: interact with the device using the spec (read/write characteristics, execute flows), use plugin shortcut tools if a plugin is loaded, extend an existing plugin with new tools, or create a new plugin using ble.plugin.template.
ble.spec.get
Get the attached spec for a connection (returns null if none attached).
ble.spec.list
List all registered specs with their metadata and matching hints.
ble.spec.read
Read full spec content, file path, and metadata by spec_id.
ble.spec.register
Register a spec file in the index. Validates YAML front-matter (requires kind: ble-protocol and name). The file path can be absolute or relative to CWD.
ble.spec.search
Full-text search over a spec's content. Returns matching snippets with line numbers and surrounding context.
ble.spec.template
Return a markdown template for a new BLE protocol spec. Optionally pre-fill with a device name.
ble.subscribe
Subscribe to notifications/indications on a characteristic.
ble.subscriptions.list
List all active subscriptions with their status, queue depth, and dropped count. Optionally filter by connection_id. Useful for recovering subscription IDs.
ble.tasks.cancel
Cancel a running background task by task_id.
ble.tasks.list
List all registered background tasks (from plugins) with their status. Shows task_id, name, running/stopped, start time, and any error.
ble.trace.status
Return tracing config and event count.
ble.trace.tail
Return last N trace events (default 50).
ble.unsubscribe
Unsubscribe from a previously created subscription.
ble.wait_notification
Block until the next single notification arrives on a subscription, or timeout. For bursty / bulk flows (e.g. downloading a dataset or log file) prefer ble.drain_notifications instead.
ble.write
Write a value to a GATT characteristic. Requires BLE_MCP_ALLOW_WRITES=true at server startup. Provide value as base64 (value_b64) or hex (value_hex).
ble.write_descriptor
Write to a GATT descriptor by handle. Requires BLE_MCP_ALLOW_WRITES=true. Rarely needed directly — bleak handles CCCD for notify/indicate automatically.

Signals

Stars: 18
Forks: 2
Open issues: 0
Weekly downloads: 67
Last commit: Mar 30, 2026 (7 months ago)
Last release: Mar 30, 2026 (7 months ago)
Last package publish: Mar 30, 2026 (7 months ago)

From GitHub (fetched Oct 24, 2026) and the package registry.

Details

Registry name: io.github.es617/ble-mcp-server
Version: 0.3.0
Auth: API key
Packages: pypi ble-mcp-serverpypi ble-mcp-serverpypi ble-mcp-server
License: MIT
Repository: github.com/es617/ble-mcp-server
First seen: Oct 24, 2026
Last checked: Oct 25, 2026
Source: Official MCP Registry github-graphql

More from es617

Cite this page

Ble MCP Server. Agent Mart. https://agentmart.dev/connectors/es617-ble-mcp-server (last updated 2026-10-25)