pod
Other formats agents might prefer:
markdownjsonllms.txt

Agent? You probably want markdown or json, or Pod over MCP.

Reported issues for unifi-mcp-server

Pod holds 20 of 30 problems reported by people outside the maintainer team. Issues filed by the project's own owners, members and collaborators are excluded entirely — a maintainer's release checklist is not a warning to a prospective user.

Back to unifi-mcp-server.

Most discussed

MCP_SERVER_TRANSPORT=streamable_http crashes with FastMCP: Unknown transport

Summary

Starting the server with the transport value currently recommended by the documentation:

MCP_SERVER_TRANSPORT=streamable_http

causes the process to exit during FastMCP startup:

ValueError: Unknown transport: streamable_http

FastMCP's server-side name for the Streamable HTTP transport is http.

Environment

  • Deployment: Docker
  • API mode: local
  • Python: 3.13
  • Configured transport: streamable_http
  • Server port: 3000
  • Repository: current main

Read the thread · 2026-08-23 · open · external user · 3 comments

CI is unreachable for fork PRs: workflow runs stuck at action_required + Mermaid check erroring, blocking all 9 open PRs

Opening this as a process/CI issue rather than a code bug: all 9 open PRs are currently unmergeable for the same reason, and it isn't anything the contributors can fix from their side.

Summary

Fork PRs never run CI, so the only check that reports a conclusion is Mermaid Diagram Sync Assistant — which has been erroring on every fork PR since late June. The automated daily review then reads that as a failing required check and posts CHANGES_REQUESTED, every day, forever.

1. Fork PR wo

Read the thread · 2026-08-06 · open · outside contributor · 3 comments

[Bug] All v2 traffic-flow tools fail with "Site does not exist" when passed a site UUID

Bug Description

get_v2_api_path() interpolates the caller-supplied site_id straight into /proxy/network/v2/api/site/{site_id}. The UUID → site-short-name translation that UniFiClient._translate_endpoint() performs only fires for /ea/sites/... endpoints; paths that already start with /proxy/network/ are passed through untouched. So every v2 traffic-flow tool sends a UUID where the v2 API requires the short name, and the controller rejects it.

This matters because list_sites ret

Read the thread · 2026-07-30 · closed · outside contributor · 5 comments

[Bug] create_wlan dry-run succeeds but confirmed 6 GHz WPA3 SSID creation fails with InvalidPayload

Bug Description

The MCP tool create_wlan failed when tested against the UDR7 Local environment.

The specific failure was creating a 6 GHz-only WPA3 PSK SSID. dry_run=true succeeded and returned a valid-looking payload preview, but the confirmed call failed with api.err.InvalidPayload / api.err.InvalidValue.

Error Message

Error calling tool 'create_wlan': API request failed: {"meta":{"rc":"error","msg":"api.err.InvalidPayload"},"data":[{"validationError":{},"rc":"error",

[Read the thread](https://github.com/enuno/unifi-mcp-server/issues/77) · 2026-05-12 · closed · external user · 4 comments

### Request - SKILL.md / cli mode

I wonder if you could package these tools as a cli with an associated SKILL.md file (or set of files)? That would make them easier to use because they wouldn't take up space in the context for conversations that don't involve Unifi. Users could leave the Unifi skill enabled all the time, vs having to enable/disable the Unifi MCP server.

There are tools that try to automatically wrap MCP servers into CLI tools and/or SKILLs. but an official version would be nice.

[Read the thread](https://github.com/enuno/unifi-mcp-server/issues/70) · 2026-05-01 · closed · external user · 7 comments

### Request - some way to reduce the tools to under 50.

FWIW the current mcp server has well over a hundred tools. That's too many for some agents like Google Antigravity, which has a limit of 50 MCP tools, summed over all enabled MCP servers.

I guess I could rebuild the unifi-mcp-server after editing it to remove some tools, but it would be nice to have an out-of-the-box solution for this.

Note that while Antigravity allows you to enable/disable individual tools, it refuses to do so if the total number of tools is greater than 50.

(Antigravity ha

[Read the thread](https://github.com/enuno/unifi-mcp-server/issues/69) · 2026-05-01 · closed · external user · 4 comments

### [Bug] Local Gateway authentication fails - all tools return 401 Unauthorized

## Bug Description
The MCP server fails to authenticate with the Local Gateway API, causing all tools to fail with 401 Unauthorized errors.

## Affected Tools
All tested tools failed with the same authentication error:
- `list_sites`
- `list_wlans`
- `list_active_clients`
- `search_devices`

## Error Details

Failed to authenticate with UniFi API: Authentication failed: {"error":{"code":401,"message":"Unauthorized"}}


## API Details
- **Environment:** Local Gateway (Local API mode)
- **AP

[Read the thread](https://github.com/enuno/unifi-mcp-server/issues/14) · 2026-01-23 · closed · external user · 5 comments

### Proposal: Major contribution - comprehensive test suite, new tools, and API audit

Hi @enuno,

I've been using unifi-mcp-server for a project and ended up making significant enhancements that I'd like to contribute back upstream. Before opening PRs, I wanted to discuss the scope and preferred approach with you.

## Summary of Changes

Over the past few weeks, I've added:

### 1. Comprehensive Test Suite
- **Before:** Limited test coverage
- **After:** 213 unit tests across all major modules
- Includes tests for: devices, clients, networks, sites, config, audit, helpers, conten

[Read the thread](https://github.com/enuno/unifi-mcp-server/issues/11) · 2026-01-06 · closed · outside contributor · 4 comments

## Most recent

### [Bug] Unifi MCP SSL Issue

<html>
<body>
<!--StartFragment--><html><head></head><body><h2>Bug Description</h2>
<p>The MCP tool <code>list_active_clients</code> (and by extension, any tool that calls <code>UniFiClient.authenticate()</code>) failed against a <strong>UDM Pro Local</strong> environment because SSL certificate verification could not be disabled. The <code>.env</code> variable documented for this purpose (<code>UNIFI_LOCAL_VERIFY_SSL</code>) is silently dropped by the provided <code>docker-compose.yml</code>, w

[Read the thread](https://github.com/enuno/unifi-mcp-server/issues/161) · 2026-08-25 · open · external user · 2 comments

### [Bug] Integration v1 sweep: 3 more models reject real controller responses, 5 tools call non-existent endpoints

## Summary

Follow-up to #100 / #103. While fixing `list_wan_connections` I promised the reviewer a sweep of the other Integration v1 code paths for the same defect class. This is that sweep.

Two distinct defect classes turned up, both making tools unusable in `UNIFI_API_TYPE=local` mode:

- **Class A — model requires fields the Integration v1 API never sends.** Same root cause as #100. `ValidationError` after a successful `200`, so the data is fetched and then thrown away.
- **Class B — the to

[Read the thread](https://github.com/enuno/unifi-mcp-server/issues/108) · 2026-08-03 · closed · outside contributor · 3 comments

### [Bug] ValidationError: FirewallPolicy.destination.matching_target missing 'WEB' enum value

## Description

`list_firewall_policies` (and by extension `get_firewall_policy`) fails with a 
Pydantic validation error when any firewall policy on the site has 
`destination.matching_target` set to `"WEB"`. Since Pydantic validates the full 
response list, a single policy with this value causes the *entire* tool call to 
fail — there's no way to retrieve any firewall policies for the site until the 
offending policy is removed or changed.

This looks like the same class of issue fixed for `AP

[Read the thread](https://github.com/enuno/unifi-mcp-server/issues/106) · 2026-08-02 · closed · external user · 2 comments

### [Bug] get_network_topology returns no device-to-device links — reads an `uplink` field the devices endpoint does not return

## Bug Description

`get_network_topology` builds device uplinks from `device.get("uplink", {})`,
but `GET /integration/v1/sites/{site_id}/devices` does not include an `uplink`
key at all. `uplink_device_id` is therefore always `None`, no uplink connections
are ever created, and `max_depth` is always `0`.

The result is a topology graph containing only client-to-device edges. The
device hierarchy — the actual point of a topology tool — is missing.

## Environment Details

unifi-mcp-server versio

[Read the thread](https://github.com/enuno/unifi-mcp-server/issues/102) · 2026-07-30 · closed · outside contributor · 2 comments

### [Bug] list_pending_devices hits a non-existent endpoint — 'pending' parsed as a deviceId

## Bug Description

`list_pending_devices` requests
`/integration/v1/sites/{site_id}/devices/pending`. The Integration v1 API has no
such route; it matches the `/devices/{deviceId}` pattern instead, so the
controller tries to parse the literal string `pending` as a device ID and
rejects the request.

The tool cannot succeed on any site — this is not environment-specific.

## Error Message

Error calling tool 'list_pending_devices': API request failed: {"statusCode":400, "statusName":"BAD_REQ

Read the thread · 2026-07-30 · closed · outside contributor · 3 comments

[Bug] list_wan_connections raises ValidationError — WANConnection requires fields the Integration API never returns

Bug Description

WANConnection marks site_id, wan_type, interface and status as required, but GET /integration/v1/sites/{site_id}/wans returns only id and name. Every response therefore fails validation and the tool is unusable in local Integration API mode.

Same failure shape as #72 / #75 / #89 — a model stricter than the API it parses.

Error Message

Error calling tool 'list_wan_connections': 4 validation errors for WANConnection
site_id
  Field required [type=missi

[Read the thread](https://github.com/enuno/unifi-mcp-server/issues/100) · 2026-07-30 · closed · outside contributor · 2 comments

### Requests to Legacy REST endpoints failing

I am trying to use unifi-mcp-server with Claude and it is failing. I requested Claude to document the error and its conditions. It provided detailed data and suggested fixes
## Bug Description

<!-- Provide a clear and concise description of the bug -->

Requests to legacy REST endpoints (list_port_forwards, get_device_connections) hang for ~4 minutes instead of failing fast, due to stacked retry/backoff on authenticate() + data call

## Error Message

[Paste the exact error message here] ``

Read the thread · 2026-07-27 · closed · external user · 3 comments

Error: Received request before initialization was complete

Title

SSE transport: tool calls fail with "Tool execution failed" despite valid connectivity and auth — likely session-init race condition

Environment

  • Image: ghcr.io/enuno/unifi-mcp-server:latest
  • Transport: SSE (MCP_SERVER_TRANSPORT=sse, port 3000)
  • Deployment: Docker Compose, container name smarthome-unifi-mcp-1, host nuc
  • UniFi API type: local (self-hosted UDM/console, not cloud)

Full compose config (keys redacted)

unifi-mcp:
  image: ghcr.io/enuno/unifi-mcp

[Read the thread](https://github.com/enuno/unifi-mcp-server/issues/96) · 2026-07-18 · open · external user · 3 comments

### [Bug] Component already exists" warning logged continuously

## "Component already exists" warning logged continuously (~every 65s) regardless of client connections

The server continuously logs WARNING Component already exists: local_provider.py:192 at a steady rate of roughly 110 occurrences/hour (~every 60-65 seconds), confirmed via Loki log aggregation over a sustained period. This happens regardless of whether an MCP client is actively connected — the rate is flat even with no active session, ruling out reconnect-driven re-registration.

### Example 

[Read the thread](https://github.com/enuno/unifi-mcp-server/issues/91) · 2026-06-13 · closed · external user · 3 comments

### [Bug] list_traffic_routes fails with ValidationError when static routes exist on site

## Bug Description

The MCP tool `list_traffic_routes` failed when tested against the **UDM SE Local** environment.

When invoked, the tool successfully reaches the UniFi controller and retrieves data from the
`/proxy/network/api/s/default/rest/routing` endpoint. However, the response contains **static route
objects** (identified by the `static-route_nexthop` key) in addition to policy-based traffic routes.
The `TrafficRoute` Pydantic model treats `action` and `match_criteria` as required fields

[Read the thread](https://github.com/enuno/unifi-mcp-server/issues/89) · 2026-06-10 · closed · external user · 2 comments

### update_network: dry_run=False always returns dry-run response; DNS fields missing from would_update (v0.2.5)

## Summary

Two related bugs in `update_network` (`src/tools/network_config.py`) cause it to **always behave as if `dry_run=True`** and to **silently drop DNS parameters** from both the preview output and the live update.

## Bug 1 — `dry_run` string coercion not applied before the branch check

### Root cause

The function signature accepts `dry_run: bool | str = False`, and a `coerce_bool()` helper already exists in `src/utils/validators.py` to handle the MCP JSON-RPC quirk where booleans arri

[Read the thread](https://github.com/enuno/unifi-mcp-server/issues/86) · 2026-05-22 · closed · external user · 2 comments

### Bug - list_vlans fails when the site contains a network with an empty vlan

## Bug Description

The MCP tool `list_vlans` fails when the site contains a network whose `vlan` field is returned as an empty string by the UniFi API (observed on WAN networks, which have no VLAN ID). The Pydantic `Network` model requires `vlan` to be a valid integer, causing validation to throw and the entire tool call to fail rather than returning the other networks successfully.

## Error Message

1 validation error for Network vlan Input should be a valid integer, unable to parse strin

Read the thread · 2026-05-03 · closed · external user · 2 comments

The remaining reports are on the project's issue tracker.