marzban-mcp

Create user

marzban_users_create

Creates a new user in a Marzban proxy panel with optional data limit, expiry, protocols, and inbounds; apply a template or explicit overrides to provision access.

Instructions

Creates a new user. dataLimit accepts a human size ("10GB"), expire a relative duration ("30d") or absolute date — both default to unlimited when omitted. templateId fills dataLimit/inbounds/expire from a user template; any field also given explicitly overrides the template value.

Input Schema

Name	Required	Description
`note`	No
`expire`	No	e.g. "30d". Omit for no expiration.
`status`	No	Defaults to active.
`proxies`	No	Protocol name -> settings, e.g. {"vless": {"id": "<uuid>"}} or {"shadowsocks": {}} to auto-generate credentials. Omit to leave unchanged on update. On create there is no server default — omitting this (without templateId) errors; provide at least one protocol with a matching inbound configured on the panel.
`inbounds`	No	Protocol name -> inbound tags to restrict this user to. Omit for all inbounds.
`username`	Yes
`dataLimit`	No	e.g. "10GB". Omit or 0 for unlimited.
`templateId`	No	Create from a user template instead of specifying proxies/inbounds by hand.
`onHoldExpireDuration`	No	Seconds the user may stay on_hold before expiring, counted from their first connection. Only meaningful when status is on_hold.
`dataLimitResetStrategy`	No

Output Schema

Name	Required	Description	Default
`note`	No
`admin`	No
`links`	No
`expire`	No
`status`	Yes
`proxies`	Yes
`inbounds`	No
`username`	Yes
`next_plan`	No
`online_at`	No
`created_at`	Yes
`data_limit`	No	data_limit can be 0 or greater
`used_traffic`	Yes
`sub_updated_at`	No
`on_hold_timeout`	No
`subscription_url`	No
`excluded_inbounds`	No
`auto_delete_in_days`	No
`sub_last_user_agent`	No
`lifetime_used_traffic`	No
`on_hold_expire_duration`	No
`data_limit_reset_strategy`	No		no_reset

Schema Changelog

Changes observed during successful MCP inspections.

Changed22 schema fields changedv0.2.4Oct 23, 2026

removedInput schema / $schema

Removed value: -"https://json-schema.org/draft/2020-12/schema"

changedInput schema / properties / dataLimit / anyOf

Previous value: -[
-  {
-    "maximum": 9007199254740991,
-    "minimum": 0,
-    "type": "integer"
-  },
-  {
-    "pattern": "^\\d+(?:[.,]\\d+)?\\s*(B|KB|KIB|MB|MIB|GB|GIB|TB|TIB|PB|PIB)?$",
-    "type": "string"
-  }
-]New value: +[
+  {
+    "minimum": 0,
+    "type": "integer"
+  },
+  {
+    "pattern": "^\\d+(?:[.,]\\d+)?\\s*(B|KB|KIB|MB|MIB|GB|GIB|TB|TIB|PB|PIB)?$",
+    "type": "string"
+  }
+]

changedInput schema / properties / expire / anyOf

Previous value: -[
-  {
-    "type": "string"
-  },
-  {
-    "maximum": 9007199254740991,
-    "minimum": 0,
-    "type": "integer"
-  }
-]New value: +[
+  {
+    "type": "string"
+  },
+  {
+    "minimum": 0,
+    "type": "integer"
+  }
+]

removedInput schema / properties / onHoldExpireDuration / maximum
```
Removed value: -9007199254740991
```
removedInput schema / properties / templateId / maximum
```
Removed value: -9007199254740991
```

removedOutput schema / $schema

Removed value: -"https://json-schema.org/draft/2020-12/schema"

changedOutput schema / properties / admin / anyOf

Previous value: -[
-  {
-    "additionalProperties": false,
-    "properties": {
-      "discord_webhook": {
-        "anyOf": [
-          {
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "is_sudo": {
-        "type": "boolean"
-      },
-      "telegram_id": {
-        "anyOf": [
-          {
-            "maximum": 9007199254740991,
-            "minimum": -9007199254740991,
-            "type": "integer"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "username": {
-        "type": "string"
-      },
-      "users_usage": {
-        "anyOf": [
-          {
-            "maximum": 9007199254740991,
-            "minimum": -9007199254740991,
-            "type": "integer"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      }
-    },
-    "required": [
-      "username",
-      "is_sudo"
-    ],
-    "type": "object"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "additionalProperties": false,
+    "properties": {
+      "discord_webhook": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "is_sudo": {
+        "type": "boolean"
+      },
+      "telegram_id": {
+        "anyOf": [
+          {
+            "type": "integer"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "username": {
+        "type": "string"
+      },
+      "users_usage": {
+        "anyOf": [
+          {
+            "type": "integer"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      }
+    },
+    "required": [
+      "username",
+      "is_sudo"
+    ],
+    "type": "object"
+  },
+  {
+    "type": "null"
+  }
+]

changedOutput schema / properties / auto_delete_in_days / anyOf

Previous value: -[
-  {
-    "anyOf": [
-      {
-        "maximum": 9007199254740991,
-        "minimum": -9007199254740991,
-        "type": "integer"
-      },
-      {
-        "type": "null"
-      }
-    ]
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "type": "integer"
+  },
+  {
+    "type": "null"
+  }
+]

changedOutput schema / properties / data_limit / anyOf

Previous value: -[
-  {
-    "maximum": 9007199254740991,
-    "minimum": -9007199254740991,
-    "type": "integer"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "type": "integer"
+  },
+  {
+    "type": "null"
+  }
+]

removedOutput schema / properties / excluded_inbounds / properties
```
Removed value: -{}
```

changedOutput schema / properties / expire / anyOf

Previous value: -[
-  {
-    "anyOf": [
-      {
-        "maximum": 9007199254740991,
-        "minimum": -9007199254740991,
-        "type": "integer"
-      },
-      {
-        "type": "null"
-      }
-    ]
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "type": "integer"
+  },
+  {
+    "type": "null"
+  }
+]

removedOutput schema / properties / inbounds / properties
```
Removed value: -{}
```
removedOutput schema / properties / lifetime_used_traffic / maximum
```
Removed value: -9007199254740991
```
removedOutput schema / properties / lifetime_used_traffic / minimum
```
Removed value: --9007199254740991
```

changedOutput schema / properties / next_plan / anyOf

Previous value: -[
-  {
-    "anyOf": [
-      {
-        "additionalProperties": false,
-        "properties": {
-          "add_remaining_traffic": {
-            "default": false,
-            "type": "boolean"
-          },
-          "data_limit": {
-            "anyOf": [
-              {
-                "maximum": 9007199254740991,
-                "minimum": -9007199254740991,
-                "type": "integer"
-              },
-              {
-                "type": "null"
-              }
-            ]
-          },
-          "expire": {
-            "anyOf": [
-              {
-                "maximum": 9007199254740991,
-                "minimum": -9007199254740991,
-                "type": "integer"
-              },
-              {
-                "type": "null"
-              }
-            ]
-          },
-          "fire_on_either": {
-            "default": true,
-            "type": "boolean"
-          }
-        },
-        "type": "object"
-      },
-      {
-        "type": "null"
-      }
-    ]
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "additionalProperties": false,
+    "properties": {
+      "add_remaining_traffic": {
+        "default": false,
+        "type": "boolean"
+      },
+      "data_limit": {
+        "anyOf": [
+          {
+            "type": "integer"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "expire": {
+        "anyOf": [
+          {
+            "type": "integer"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "fire_on_either": {
+        "default": true,
+        "type": "boolean"
+      }
+    },
+    "type": "object"
+  },
+  {
+    "type": "null"
+  }
+]

changedOutput schema / properties / note / anyOf

Previous value: -[
-  {
-    "anyOf": [
-      {
-        "type": "string"
-      },
-      {
-        "type": "null"
-      }
-    ]
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]

changedOutput schema / properties / on_hold_expire_duration / anyOf

Previous value: -[
-  {
-    "anyOf": [
-      {
-        "maximum": 9007199254740991,
-        "minimum": -9007199254740991,
-        "type": "integer"
-      },
-      {
-        "type": "null"
-      }
-    ]
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "type": "integer"
+  },
+  {
+    "type": "null"
+  }
+]

removedOutput schema / properties / proxies / additionalProperties / properties
```
Removed value: -{}
```
removedOutput schema / properties / proxies / properties
```
Removed value: -{}
```

changedOutput schema / properties / sub_last_user_agent / anyOf

Previous value: -[
-  {
-    "anyOf": [
-      {
-        "type": "string"
-      },
-      {
-        "type": "null"
-      }
-    ]
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]

removedOutput schema / properties / used_traffic / maximum
```
Removed value: -9007199254740991
```
removedOutput schema / properties / used_traffic / minimum
```
Removed value: --9007199254740991
```

Changed6 schema fields changedv0.2.3Sep 7, 2026

changedInput schema / properties / proxies / description

Previous value: -"Protocol name -> settings, e.g. {\"vless\": {\"id\": \"<uuid>\"}}. Omit to leave unchanged (update) or use server defaults (create)."New value: +"Protocol name -> settings, e.g. {\"vless\": {\"id\": \"<uuid>\"}} or {\"shadowsocks\": {}} to auto-generate credentials. Omit to leave unchanged on update. On create there is no server default — omitting this (without templateId) errors; provide at least one protocol with a matching inbound configured on the panel."

removedOutput schema / properties / created_at / format
```
Removed value: -"date-time"
```

removedOutput schema / properties / created_at / pattern

Removed value: -"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|))$"

changedOutput schema / properties / on_hold_timeout / anyOf

Previous value: -[
-  {
-    "anyOf": [
-      {
-        "format": "date-time",
-        "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|))$",
-        "type": "string"
-      },
-      {
-        "type": "null"
-      }
-    ]
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]

changedOutput schema / properties / online_at / anyOf

Previous value: -[
-  {
-    "anyOf": [
-      {
-        "format": "date-time",
-        "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|))$",
-        "type": "string"
-      },
-      {
-        "type": "null"
-      }
-    ]
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]

changedOutput schema / properties / sub_updated_at / anyOf

Previous value: -[
-  {
-    "anyOf": [
-      {
-        "format": "date-time",
-        "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|))$",
-        "type": "string"
-      },
-      {
-        "type": "null"
-      }
-    ]
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]

First observedv0.2.2Sep 2, 2026

TDQS

A3.6/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=false and destructiveHint=false, so the safety profile is covered. The description does add real value by disclosing the unlimited defaults for dataLimit/expire and the template-override precedence rule. It omits the create-specific failure mode (omitting proxies without a template errors) and any permission or side-effect details, which live only in the schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three tight sentences, front-loaded with the core action before format and template details. Each sentence carries non-redundant information, though the param-format sentences partially mirror the schema descriptions.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need not be explained, and the 70%-covered 10-param schema fills most gaps for flags like status and onHoldExpireDuration. The description covers the three most semantically tricky parameters; the main residual gap is not restating that proxies is effectively required on create without a templateId.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 70% schema coverage the baseline is 3, and the description goes beyond it: it explains accepted formats for dataLimit ("10GB") and expire ("30d" or absolute date), and clarifies the override precedence between templateId and explicit fields, which the schema does not state. It says nothing about username constraints, status, onHoldExpireDuration, or dataLimitResetStrategy, leaving those to the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ("Creates a new user"), which clearly separates it from update/activate/hold siblings in the marzban_users family. It stops short of explicitly routing an agent between create and marzban_users_update or the template path, but the action is unmistakable.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The templateId sentence implies an alternative creation path (template vs. hand-specified fields) but never frames it as guidance, and there is no statement of when to prefer this over sibling tools like marzban_users_update. Usage is inferable rather than stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server