Python Matter Server

8.1.2 verified Mon Apr 27 auth: no python

Python-based server for interacting with Matter smart home devices, part of the Open Home Foundation ecosystem. Current version 8.1.2, requires Python >=3.12. Rapid development with frequent breaking changes.

pip install python-matter-server

Common errors

error ModuleNotFoundError: No module named 'matter_server' ↓

cause Package not installed.

fix

Run 'pip install python-matter-server'.

error from matter_server import MatterServer -> ImportError: cannot import name 'MatterServer' from 'matter_server' ↓

cause MatterServer was moved to matter_server.server in v7.

fix

Use 'from matter_server.server import MatterServer'.

error TypeError: Client() missing required 'server_info' argument ↓

cause Incorrect instantiation pattern (old API).

fix

Use MatterClient(server_url, auth_token) constructor directly.

Warnings

breaking Breaking change in v7: 'MatterServer' class moved from 'matter_server' to 'matter_server.server'. Update imports. ↓

fix Use 'from matter_server.server import MatterServer' instead of 'from matter_server import MatterServer'.

breaking In v8, the WebSocket protocol changed: authentication now requires a token or empty string. Old versions used a different handshake. ↓

fix Ensure client passes an auth token (or empty string) when connecting via WebSocket.

breaking Python 3.11 and lower are no longer supported. Requires Python >=3.12. ↓

fix Upgrade Python to 3.12 or later.

Imports

MatterServer
wrong
```
from python_matter_server import MatterServer
```
correct
```
from matter_server.server import MatterServer
```
Incorrect module path; the package's import prefix is 'matter_server' not 'python_matter_server'.

MatterClient

from matter_server.client import MatterClient

Quickstart

Connects to a local Matter Server instance and fetches all nodes. Requires a running Matter Server (e.g., via pip install python-matter-server and running matter-server).

import asyncio
from matter_server.client import MatterClient

async def main():
    client = MatterClient("ws://localhost:5580/ws", "")
    await client.connect()
    nodes = await client.get_nodes()
    print(nodes)

asyncio.run(main())