MQTT Specification MCP server

mqtt-spec-mcp

<!-- mcp-name: io.github.cartertinney/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.

environment variables, configuration files, or flags.

1. Install uv.
2. Add the server to your client, as shown below. The server needs no

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 CLI

VS 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"]
    }
  }
}

claudedesktopconfig.json. Quit and reopen Claude after saving.

• Claude Desktop: Settings → Developer → Edit Config opens

one project.

• Cursor: use ~/.cursor/mcp.json for all projects, or .cursor/mcp.json in

• Zed: put the same entry under context_servers in 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

Shortened. The full README is on GitHub.