uvx / pipx
uvx (from uv) is the fastest way to try mcp-unifi on a machine that already has Python tooling. With MCP_TRANSPORT=stdio set, the server runs over stdio, the transport Claude Desktop and Claude Code’s stdio path spawn. Nothing is installed system-wide; uvx caches the package in its own directory.
One-off run
Section titled “One-off run”The server’s default transport is Streamable HTTP, which refuses to start without a bearer token. For a stdio run, set MCP_TRANSPORT=stdio:
MCP_TRANSPORT=stdio uvx --from git+https://github.com/pete-builds/mcp-unifi mcp-unifiThat command resolves the repo, builds a venv, installs the package, and starts the server on stdio. A stdio server waits for an MCP client on stdin, so in a terminal it sits silent until you press Ctrl+C. STUB_MODE defaults to true, so with no other settings it serves mock data.
To pin a release, append @<tag> to the git URL, where <tag> is a release tag from the releases page:
MCP_TRANSPORT=stdio uvx --from git+https://github.com/pete-builds/mcp-unifi@<tag> mcp-unifiWire into Claude Code
Section titled “Wire into Claude Code”Add it as a stdio MCP server in Claude Code (user scope):
claude mcp add --transport stdio --scope user unifi \ --env MCP_TRANSPORT=stdio \ -- uvx --from git+https://github.com/pete-builds/mcp-unifi mcp-unifiSTUB_MODE defaults to true, so that registration serves made-up sample data with no hardware. For your own network, pass the gateway env vars as well. This form is read-only and pinned to a release; drop MCP_UNIFI_READONLY=true when you want Claude to make changes:
claude mcp add --transport stdio --scope user unifi \ --env MCP_TRANSPORT=stdio \ --env STUB_MODE=false \ --env MCP_UNIFI_READONLY=true \ --env UNIFI_HOST=192.168.1.1 \ --env UNIFI_API_KEY=<your-local-api-key> \ -- uvx --from git+https://github.com/pete-builds/mcp-unifi@v0.29.0 mcp-unifiLeaving STUB_MODE out while setting a host and key still serves the simulator’s data. From 0.29.0 the server then logs a warning at startup and every answer says the data is simulated; v0.28.0 says nothing.
Tested where: the uvx route was tested on macOS (Apple silicon) in stub mode. Not yet tested on Windows.
Verify with claude mcp list. The unifi entry should report Connected.
pipx works too if you don’t have uv installed:
pipx install git+https://github.com/pete-builds/mcp-unifiMCP_TRANSPORT=stdio mcp-unifipipx installs the package globally for your user; remove it later with pipx uninstall mcp-unifi.
- The
mcp-unificonsole script does not pick a transport for you. UnlessMCP_TRANSPORT=stdiois set, it starts the Streamable HTTP transport and exits withHTTP transport requires MCP_UNIFI_AUTH_TOKENSwhen no token is configured. Every stdio command on this page therefore sets it. If you want Streamable HTTP, use the Docker install instead. - Multi-controller config via
MCP_UNIFI_CONTROLLERS_FILEworks the same as in Docker; point the env var at a YAML file the uvx process can read. - The audit log path defaults to
audit.jsonlin the CWD of whereveruvxran. SetMCP_UNIFI_AUDIT_PATH=/path/to/audit.jsonlto override.