mqtt-spec-mcp
Provides offline tools for searching and citing the OASIS MQTT 3.1.1 and MQTT 5.0 specifications, including excerpt search, section retrieval, outlines, and exact lookups for packets, properties, codes, requirements, and glossary terms.
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., "@mqtt-spec-mcp Search MQTT 5.0 for session expiry and cite the section."
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.
mqtt-spec-mcp
An offline Model Context Protocol server for searching and citing the OASIS MQTT 3.1.1 and MQTT 5.0 specifications. Agents get focused source excerpts instead of loading a whole specification.
Four read-only tools for search, section retrieval, outlines, and exact lookups.
Bundled indexes: no network, database, embeddings, or LLM at query time.
Explicit version selection on every call; no default or cross-version results.
Bounded section pages and compact search evidence packs with source links.
The server retrieves evidence; the agent does the reasoning. OASIS publications remain authoritative, and retrieved excerpts are not a guarantee of a correct answer.
Setup
Your MCP client starts the server on your machine and talks to it over stdio.
There is no separate install step: configure the client to run
uvx mqtt-spec-mcp, and uv downloads the package
from PyPI the first time, caches it, and starts it. uv also fetches a compatible
Python (3.10 or newer) if you don't have one. Each time the client starts the
server, uv checks PyPI for a newer release, so updates arrive automatically.
Add the server to your client, as shown below. The server needs no environment variables, configuration files, or flags.
The server is also listed in the MCP Registry
as io.github.cartertinney/mqtt-spec-mcp, for clients that install from it.
Claude Code, Codex, GitHub Copilot CLI, and Gemini CLI
Each of these adds the server for all your projects with one command:
claude mcp add --scope user mqtt-spec -- uvx mqtt-spec-mcp # Claude Code
codex mcp add mqtt-spec -- uvx mqtt-spec-mcp # OpenAI Codex CLI and IDE extension
copilot mcp add mqtt-spec -- uvx mqtt-spec-mcp # GitHub Copilot CLI
gemini mcp add --scope user mqtt-spec uvx mqtt-spec-mcp # Gemini CLIVS Code (GitHub Copilot)
Add the server to your user profile from a terminal:
code --add-mcp '{"name":"mqtt-spec","type":"stdio","command":"uvx","args":["mqtt-spec-mcp"]}'Or run MCP: Add Server from the Command Palette, or add it to one project's
.vscode/mcp.json:
{
"servers": {
"mqtt-spec": {
"type": "stdio",
"command": "uvx",
"args": ["mqtt-spec-mcp"]
}
}
}Claude Desktop, Cursor, and other clients
Most other clients read the same mcpServers entry:
{
"mcpServers": {
"mqtt-spec": {
"command": "uvx",
"args": ["mqtt-spec-mcp"]
}
}
}Claude Desktop: Settings → Developer → Edit Config opens
claude_desktop_config.json. Quit and reopen Claude after saving.Cursor: use
~/.cursor/mcp.jsonfor all projects, or.cursor/mcp.jsonin one project.Zed: put the same entry under
context_serversin its settings file.
ChatGPT and the OpenAI Agents SDK
ChatGPT connects only to remote MCP servers over HTTPS, so it can't start this
local server; use the Codex CLI or IDE extension instead (above). In an agent
built with the OpenAI Agents SDK,
connect with MCPServerStdio(params={"command": "uvx", "args": ["mqtt-spec-mcp"]}).
Without uv
Install the package with pipx install mqtt-spec-mcp, or with
pip install mqtt-spec-mcp in a Python 3.10+ environment. Then configure your
client to run the command mqtt-spec-mcp, with no arguments, instead of
uvx mqtt-spec-mcp.
Troubleshooting and upgrades
The client can't find
uvx. Desktop apps often don't see your shell'sPATH. Use the absolute path printed bywhich uvx(macOS and Linux) orwhere uvx(Windows).The first start times out. The first launch downloads the package, which can take a few seconds. Download it ahead of time with
uvx --from mqtt-spec-mcp python -c pass.Updates. A new release is used from the next time your client starts the server. uv reuses PyPI's answer for up to 10 minutes, so a release can take that long to appear. After an update, start a new conversation so the client drops cached tool schemas. To stay on one version, use
mqtt-spec-mcp@0.1.0in place ofmqtt-spec-mcpin the client's arguments.No network access. The server works offline, but starting it with
uvxneeds to reach PyPI unless uv checked within the last 10 minutes. To run without network access, install it once withuv tool install mqtt-spec-mcpand configure the client to runmqtt-spec-mcp.uvx mqtt-spec-mcpthen runs the installed copy as well, and updates come only fromuv tool upgrade mqtt-spec-mcp.
Related MCP server: standards-mcp
Tools
Every call requires version: exactly "3.1.1" or "5.0".
Tool | Use |
| Find excerpts by key terms, section id, or requirement label. |
| Read a section, with bounded pages and continuation cursors. |
| Browse section ids and titles without body text. |
| Look up packets, properties, codes, requirements, or glossary terms. |
Example tool arguments:
{"version": "5.0", "query": "Receive Maximum default; QoS 0 Receive Maximum"}Use that with mqtt_spec_search. For an exact lookup with mqtt_spec_lookup:
{"version": "3.1.1", "kind": "return_code", "query": "0x80", "packet": "SUBACK"}The latter returns Failure. The same value in MQTT 5.0 is Unspecified error: version-specific labels and codes must not be carried between versions.
Guidance for agents
Ask which MQTT version the user means if they have not specified one.
Look up an exact entity, or search with the question's key terms. Separate parts of a question with
;.Answer from the evidence, preserving MUST/SHOULD/MAY and their conditions. Cite the version and section beside each claim.
Search excerpts can omit exceptions. Before claiming silence, optionality, or no exception, fetch the deciding section if it is excerpted or absent. The server recommends at most one fetch and one repeat search per version.
For comparisons, query each version separately. A miss in one says nothing about the other.
See the tool reference for all parameters, pagination, result formats, and errors.
Sources and limitations
Version | Indexed publication |
3.1.1 | MQTT Version 3.1.1 Plus Errata 01, 10 December 2015 |
5.0 | MQTT Version 5.0, 7 March 2019 |
Indexes are generated from pinned source documents and validated at startup. They are transformed retrieval aids, not official publications. MQTT 3.1 (pre-OASIS) is not supported, and this is not a broker or a conformance validator.
Limitations and roadmap describe known retrieval gaps. Benchmarks covers the offline regression checks and reports from historical agent evaluations. Those evaluations used a private harness, corpus, and raw runs, so they cannot be reproduced from this repository.
Development
See development and release checks for running from a checkout, testing, rebuilding indexes, and releasing. Benchmark checks are checkout-only and are not shipped with the server.
License
The code is MIT licensed. Specification text in the indexes and returned excerpts is copyright OASIS Open, not MIT licensed. NOTICE contains the source attribution, transformation details, and OASIS notices.
Available Tools
4 toolsmqtt_spec_getMQTT spec get sectionARead-onlyIdempotent
One section of one MQTT version as Markdown pages; continue a page with its Next cursor.
Inputs: section (required), version (required), cursor.
mqtt_spec_lookupMQTT spec lookupBRead-onlyIdempotent
Exact entry for one packet, property or reason_code (5.0), return_code (3.1.1), requirement label or glossary term.
Inputs: kind (required), query (required), version (required), packet.
mqtt_spec_outlineMQTT spec outlineBRead-onlyIdempotent
Section ids and titles of one MQTT version, for browsing.
Inputs: version (required), parent.
mqtt_spec_searchMQTT spec searchBRead-onlyIdempotent
Evidence from one MQTT version: excerpts of the sections that best match the question.
Inputs: query (required), version (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
Each tool has a recognizable retrieval role: outline for browsing, search for ranked excerpts, get for full section text with pagination, lookup for exact named entries. Search, get, and lookup all retrieve spec content and could occasionally be confused, but the descriptions clearly delineate excerpt vs. full section vs. exact entry.
All four tools share a consistent mqtt_spec_ prefix and snake_case form, which makes the set easy to scan. The suffix mix is minor ('outline' and 'lookup' read as nouns while 'search' and 'get' are verbs), but the pattern is still predictable.
Four tools is lean but sensible for a read-only spec retrieval server, with each tool covering a distinct access pattern (browse, search, read, exact lookup). It borders on thin since there is no separate tool to enumerate the available MQTT versions.
The surface covers the core documentation workflows: navigation, discovery, full-text retrieval with cursor pagination, and precise term/identifier lookup across versions. Minor gaps remain, such as no way to list supported versions or compare sections between versions, but agents can work around these via outline.
Maintenance
Related MCP Connectors
License-checked research archive and technical-spec search for AI agents. Pay per call via x402.
Agentic search over your Dewey document collections from any MCP-compatible client.
Knowledge base MCP for AI agents on iknow.dev. Search, read, and maintain via OAuth.
Make your knowledge agent-ready. One MCP endpoint, 5 connectors, 3 search modes.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to search and read offline documentation from synced libraries via MCP tools, providing hybrid keyword and semantic search without network calls.1MIT
- AlicenseAqualityCmaintenanceEnables AI agents to search, fetch, and apply portable engineering standards over MCP, keyless and offline.4MIT
- AlicenseAqualityBmaintenanceEnables developers to index and search their own local PDF, DOCX, Markdown, and text documents from an MCP client or terminal, combining semantic similarity with keyword matching for exact technical terms. Everything runs on the user's machine with no API key, Docker, or external database, so private documents stay private and work offline after the initial model download.9MIT
- AlicenseAqualityCmaintenanceEnables MCP-capable clients to search team knowledge, browse an integration catalog, and get sourced product answers through deterministic, offline tools.34 npmMIT