docs: add MCP server documentation for v1.3.0

- New user-guide/mcp-server.rst: full setup guide with Claude Desktop
  config, tool reference table, and example conversations
- index.rst: added MCP card to quick-start grid and features grid,
  added mcp-server to User Guide toctree
- installation.rst: added MCP optional dependency section, bump version
- changelog.rst: added v1.3.0 and v1.2.1 entries

Author: drtinkerer

docs/changelog.rst

@@ -6,6 +6,29 @@ All notable changes to this project will be documented in this file.
 The format is based on `Keep a Changelog <https://keepachangelog.com/en/1.0.0/>`_,
 and this project adheres to `Semantic Versioning <https://semver.org/spec/v2.0.0.html>`_.
 
+[1.3.0] - 2026-03-31
+---------------------
+
+Added
+~~~~~
+
+- **MCP Server** (``netbird.mcp.server``) — 25 NetBird management tools exposed via `Model Context Protocol <https://modelcontextprotocol.io>`_
+
+  - AI assistants (Claude Desktop, etc.) can now manage NetBird resources through natural language
+  - Tools cover: account, users, peers, groups, policies, networks, setup keys, DNS, posture checks, audit events, network diagrams
+  - See :doc:`user-guide/mcp-server` for setup instructions
+
+- **``mcp`` optional dependency** — ``mcp[cli]>=1.0.0`` via ``pip install "netbird[mcp]"``
+- **``netbird-mcp`` CLI entry point** — Start the MCP server from the command line
+
+[1.2.1] - 2026-03-28
+---------------------
+
+Fixed
+~~~~~
+
+- **PolicyRule** ``sources`` / ``destinations`` — Changed type from ``List[Dict]`` to ``List[Union[str, Dict]]``. The NetBird API expects plain string group IDs on writes (POST/PUT) but returns full objects on reads (GET).
+
 [1.2.0] - 2026-03-27
 ---------------------
 

docs/index.rst

@@ -32,6 +32,12 @@ NetBird Python Client
 
         Installation guide and requirements
 
+    .. grid-item-card:: MCP Server
+        :link: user-guide/mcp-server
+        :link-type: doc
+
+        Use NetBird with AI assistants via Model Context Protocol
+
 Features
 --------
 
@@ -61,6 +67,10 @@ Features
 
         Python 3.9+ (supports 3.9-3.14)
 
+    .. grid-item-card:: MCP Server
+
+        25 tools for AI assistants via Model Context Protocol
+
 Architecture
 ------------
 
@@ -227,6 +237,7 @@ Cloud Resources
    :caption: User Guide
 
    user-guide/authentication
+   user-guide/mcp-server
    user-guide/network-visualization
    user-guide/error-handling
 

docs/installation.rst

@@ -74,6 +74,18 @@ For generating network topology diagrams:
 
    # Mermaid requires no additional Python dependencies
 
+MCP Server (AI Assistants)
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To use NetBird with AI assistants via the Model Context Protocol:
+
+.. code-block:: bash
+
+   pip install "netbird[mcp]"
+
+This installs `mcp[cli] <https://pypi.org/project/mcp/>`_ and the ``netbird-mcp`` CLI entry point.
+See :doc:`user-guide/mcp-server` for setup instructions.
+
 Development Tools
 ~~~~~~~~~~~~~~~~~
 
@@ -98,7 +110,7 @@ Verification
 .. code-block:: python
 
    import netbird
-   print(netbird.__version__)  # Should print "1.2.0"
+   print(netbird.__version__)  # Should print "1.3.0"
 
 Virtual Environments
 --------------------

docs/user-guide/mcp-server.rst

@@ -0,0 +1,269 @@
+MCP Server
+==========
+
+The NetBird Python Client includes a built-in `Model Context Protocol <https://modelcontextprotocol.io>`_ (MCP) server that exposes 25 NetBird management tools to AI assistants like `Claude Desktop <https://claude.ai>`_.
+
+This lets you manage your NetBird network through natural language — no scripting required.
+
+Installation
+------------
+
+The MCP server requires the optional ``mcp`` dependency:
+
+.. code-block:: bash
+
+   pip install "netbird[mcp]"
+
+Configuration
+-------------
+
+The server reads credentials from environment variables:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 70
+
+   * - Variable
+     - Description
+   * - ``NETBIRD_HOST``
+     - NetBird API host (e.g. ``api.netbird.io`` or ``netbird.yourcompany.com``)
+   * - ``NETBIRD_API_TOKEN``
+     - Personal Access Token from the NetBird dashboard
+
+Claude Desktop Setup
+--------------------
+
+Add the following to your Claude Desktop configuration file:
+
+- **macOS**: ``~/Library/Application Support/Claude/claude_desktop_config.json``
+- **Windows**: ``%APPDATA%\Claude\claude_desktop_config.json``
+
+.. code-block:: json
+
+   {
+     "mcpServers": {
+       "netbird": {
+         "command": "netbird-mcp",
+         "env": {
+           "NETBIRD_HOST": "api.netbird.io",
+           "NETBIRD_API_TOKEN": "your-api-token"
+         }
+       }
+     }
+   }
+
+Restart Claude Desktop after saving. You should see NetBird tools available in the conversation.
+
+Self-Hosted NetBird
+~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: json
+
+   {
+     "mcpServers": {
+       "netbird": {
+         "command": "netbird-mcp",
+         "env": {
+           "NETBIRD_HOST": "netbird.yourcompany.com",
+           "NETBIRD_API_TOKEN": "your-api-token"
+         }
+       }
+     }
+   }
+
+Running the Server Manually
+---------------------------
+
+.. code-block:: bash
+
+   NETBIRD_HOST=api.netbird.io NETBIRD_API_TOKEN=your-token netbird-mcp
+
+Or using ``python -m``:
+
+.. code-block:: bash
+
+   python -m netbird.mcp.server
+
+Available Tools
+---------------
+
+The server exposes 25 tools organized by resource:
+
+Account
+~~~~~~~
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 70
+
+   * - Tool
+     - Description
+   * - ``get_account``
+     - Get the current NetBird account settings and configuration
+
+Users
+~~~~~
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 70
+
+   * - Tool
+     - Description
+   * - ``get_current_user``
+     - Get the currently authenticated user's profile and permissions
+   * - ``list_users``
+     - List all users in the NetBird account
+
+Peers
+~~~~~
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 70
+
+   * - Tool
+     - Description
+   * - ``list_peers``
+     - List all peers with connection status and IP addresses
+   * - ``get_peer``
+     - Get details of a specific peer by ID
+   * - ``update_peer``
+     - Update a peer's name, SSH access, or login expiration
+   * - ``delete_peer``
+     - Remove a peer from the network
+   * - ``get_peer_accessible_peers``
+     - List all peers a given peer can access based on current policies
+
+Groups
+~~~~~~
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 70
+
+   * - Tool
+     - Description
+   * - ``list_groups``
+     - List all peer groups with member counts
+   * - ``get_group``
+     - Get details of a specific group including its members
+   * - ``create_group``
+     - Create a new peer group with optional initial members
+   * - ``update_group``
+     - Update a group's name or member list
+   * - ``delete_group``
+     - Delete a peer group
+
+Policies
+~~~~~~~~
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 70
+
+   * - Tool
+     - Description
+   * - ``list_policies``
+     - List all access control policies with their rules
+   * - ``create_policy``
+     - Create a new policy with protocol, port, and direction control
+   * - ``delete_policy``
+     - Delete an access control policy
+
+Networks
+~~~~~~~~
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 70
+
+   * - Tool
+     - Description
+   * - ``list_networks``
+     - List all networks with their resources and routers
+   * - ``get_network``
+     - Get a network with its resources and routers included
+
+Setup Keys
+~~~~~~~~~~
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 70
+
+   * - Tool
+     - Description
+   * - ``list_setup_keys``
+     - List all setup keys with validity and usage stats
+   * - ``create_setup_key``
+     - Create a setup key for enrolling new peers
+
+DNS
+~~~
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 70
+
+   * - Tool
+     - Description
+   * - ``list_nameservers``
+     - List all DNS nameserver groups
+   * - ``get_dns_settings``
+     - Get the global DNS settings for the account
+
+Posture Checks & Audit
+~~~~~~~~~~~~~~~~~~~~~~~
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 70
+
+   * - Tool
+     - Description
+   * - ``list_posture_checks``
+     - List all device posture checks (compliance policies)
+   * - ``get_audit_events``
+     - Get recent audit log events showing account activity
+
+Diagrams
+~~~~~~~~
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 70
+
+   * - Tool
+     - Description
+   * - ``generate_network_diagram``
+     - Generate a network topology diagram (Mermaid, Graphviz, or Diagrams)
+
+Example Conversations
+---------------------
+
+Once connected to Claude Desktop, you can ask questions like:
+
+.. code-block:: text
+
+   "List all peers and show which ones are currently connected"
+
+   "Create a policy called 'SSH Access' allowing the DevOps group
+    to reach port 22 on the Servers group"
+
+   "Generate a Mermaid diagram of the current network topology"
+
+   "Create a reusable setup key called 'Office-Onboarding' that expires
+    in 7 days and auto-assigns peers to the Office group"
+
+   "Show me all audit events from the last 24 hours"
+
+   "Which peers can the peer named 'laptop-01' access?"
+
+API Reference
+-------------
+
+.. automodule:: netbird.mcp.server
+   :members:
+   :undoc-members:
+   :show-inheritance: