# Users

## Get User

`TOOL discourse_get_user`

Get user info. Returns JSON with id, username, name, trust_level, created_at, bio, admin, and moderator.

Authentication: no security requirement declared for this operation.

Parameters:

- `username` (argument, string, required)
  Type: string
  
  minLength: 1

Declared MCP annotations:

```json
{
  "readOnlyHint": true,
  "destructiveHint": false,
  "idempotentHint": true,
  "openWorldHint": true
}
```

## Examples

### JSON-RPC

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "discourse_get_user",
    "arguments": {
        "username": "string"
      }
  }
}
```

### TypeScript

```typescript
const result = await client.callTool({
  "name": "discourse_get_user",
  "arguments": {
    "username": "string"
  }
});
```

### Python

```python
result = await session.call_tool("discourse_get_user", arguments={
  "username": "string"
})
```


## List User Posts

`TOOL discourse_list_user_posts`

Get paginated list of user posts/replies. Returns JSON object with posts array (id, topic_id, post_number, slug, title, created_at, excerpt, category_id) and meta (page, limit, has_more).

Authentication: no security requirement declared for this operation.

Parameters:

- `username` (argument, string, required)
  Type: string
  
  minLength: 1

- `page` (argument, integer, optional)
  Type: integer
  
  minimum: 0

- `limit` (argument, integer, optional) - Posts per page (max 50, default 30)
  Type: integer
  
  Posts per page (max 50, default 30)
  
  minimum: 1
  
  maximum: 50

Declared MCP annotations:

```json
{
  "readOnlyHint": true,
  "destructiveHint": false,
  "idempotentHint": true,
  "openWorldHint": true
}
```

## Examples

### JSON-RPC

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "discourse_list_user_posts",
    "arguments": {
        "username": "string",
        "page": 0,
        "limit": 1
      }
  }
}
```

### TypeScript

```typescript
const result = await client.callTool({
  "name": "discourse_list_user_posts",
  "arguments": {
    "username": "string",
    "page": 0,
    "limit": 1
  }
});
```

### Python

```python
result = await session.call_tool("discourse_list_user_posts", arguments={
  "username": "string",
  "page": 0,
  "limit": 1
})
```


## List Users

`TOOL discourse_list_users`

List users via admin API. Requires admin API key. Returns ~100 users per page (Discourse's fixed page size). Returns JSON with users array and pagination meta.

Authentication: no security requirement declared for this operation.

Parameters:

- `query` (argument, string, optional) - User query type
  Type: string
  
  User query type
  
  default: "active"
  
  enum: ["active","new","staff","suspended","silenced","pending","staged"]

- `filter` (argument, string, optional) - Search by username, email, or IP address
  Type: string
  
  Search by username, email, or IP address

- `order` (argument, string, optional) - Sort order field
  Type: string
  
  Sort order field
  
  enum: ["created","last_emailed","seen","username","trust_level","days_visited","posts"]

- `asc` (argument, boolean, optional) - Sort ascending (default: false/descending)
  Type: boolean
  
  Sort ascending (default: false/descending)
  
  default: false

- `page` (argument, integer, optional) - Page number (0-indexed)
  Type: integer
  
  Page number (0-indexed)
  
  minimum: 0

Declared MCP annotations:

```json
{
  "readOnlyHint": true,
  "destructiveHint": false,
  "idempotentHint": true,
  "openWorldHint": true
}
```

## Examples

### JSON-RPC

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "discourse_list_users",
    "arguments": {
        "query": "active",
        "filter": "string",
        "order": "created",
        "asc": false,
        "page": 0
      }
  }
}
```

### TypeScript

```typescript
const result = await client.callTool({
  "name": "discourse_list_users",
  "arguments": {
    "query": "active",
    "filter": "string",
    "order": "created",
    "asc": false,
    "page": 0
  }
});
```

### Python

```python
result = await session.call_tool("discourse_list_users", arguments={
  "query": "active",
  "filter": "string",
  "order": "created",
  "asc": false,
  "page": 0
})
```


## Create User

`TOOL discourse_create_user`

Create a user through Discourse's signup API using a global admin API key. Reports whether upstream confirmed creation; anti-enumeration responses without user_id remain indeterminate. Optional avatar assignment runs only after confirmed creation.

Authentication: no security requirement declared for this operation.

Parameters:

- `username` (argument, string, required)
  Type: string
  
  minLength: 1
  
  maxLength: 20

- `email` (argument, string, email, required)
  Type: string, email

- `name` (argument, string, required)
  Type: string
  
  minLength: 1
  
  maxLength: 255

- `password` (argument, string, required)
  Type: string
  
  minLength: 10
  
  maxLength: 200

- `active` (argument, boolean, optional)
  Type: boolean
  
  default: true

- `approved` (argument, boolean, optional)
  Type: boolean
  
  default: true

- `upload_id` (argument, integer, optional) - Avatar upload_id (from discourse_upload_file)
  Type: integer
  
  Avatar upload_id (from discourse_upload_file)
  
  exclusiveMinimum: 0

## Examples

### JSON-RPC

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "discourse_create_user",
    "arguments": {
        "username": "string",
        "email": "user@example.com",
        "name": "string",
        "password": "string",
        "active": true,
        "approved": true,
        "upload_id": 0
      }
  }
}
```

### TypeScript

```typescript
const result = await client.callTool({
  "name": "discourse_create_user",
  "arguments": {
    "username": "string",
    "email": "user@example.com",
    "name": "string",
    "password": "string",
    "active": true,
    "approved": true,
    "upload_id": 0
  }
});
```

### Python

```python
result = await session.call_tool("discourse_create_user", arguments={
  "username": "string",
  "email": "user@example.com",
  "name": "string",
  "password": "string",
  "active": true,
  "approved": true,
  "upload_id": 0
})
```


## Update User

`TOOL discourse_update_user`

Update user profile fields. If upload_id is provided, also sets the user's avatar. Returns JSON with success status and updated user details.

Authentication: no security requirement declared for this operation.

Parameters:

- `username` (argument, string, required) - Username of user to update
  Type: string
  
  Username of user to update
  
  minLength: 1

- `name` (argument, string, optional) - Display name
  Type: string
  
  Display name

- `bio_raw` (argument, string, optional) - Bio in markdown
  Type: string
  
  Bio in markdown

- `location` (argument, string, optional) - Location
  Type: string
  
  Location

- `website` (argument, string, uri, optional) - Website URL
  Type: string, uri
  
  Website URL

- `title` (argument, string, optional) - User title
  Type: string
  
  User title

- `date_of_birth` (argument, string, optional) - Date of birth (YYYY-MM-DD)
  Type: string
  
  Date of birth (YYYY-MM-DD)
  
  pattern: "^\\d{4}-\\d{2}-\\d{2}$"

- `locale` (argument, string, optional) - Language preference
  Type: string
  
  Language preference

- `profile_background_upload_url` (argument, string, optional) - Profile background image URL
  Type: string
  
  Profile background image URL

- `card_background_upload_url` (argument, string, optional) - Card background image URL
  Type: string
  
  Card background image URL

- `upload_id` (argument, integer, optional) - Avatar upload_id (from discourse_upload_file)
  Type: integer
  
  Avatar upload_id (from discourse_upload_file)
  
  exclusiveMinimum: 0

## Examples

### JSON-RPC

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "discourse_update_user",
    "arguments": {
        "username": "string",
        "name": "string",
        "bio_raw": "string",
        "location": "string",
        "website": "https://example.com",
        "title": "string",
        "date_of_birth": "string",
        "locale": "string",
        "profile_background_upload_url": "string",
        "card_background_upload_url": "string",
        "upload_id": 0
      }
  }
}
```

### TypeScript

```typescript
const result = await client.callTool({
  "name": "discourse_update_user",
  "arguments": {
    "username": "string",
    "name": "string",
    "bio_raw": "string",
    "location": "string",
    "website": "https://example.com",
    "title": "string",
    "date_of_birth": "string",
    "locale": "string",
    "profile_background_upload_url": "string",
    "card_background_upload_url": "string",
    "upload_id": 0
  }
});
```

### Python

```python
result = await session.call_tool("discourse_update_user", arguments={
  "username": "string",
  "name": "string",
  "bio_raw": "string",
  "location": "string",
  "website": "https://example.com",
  "title": "string",
  "date_of_birth": "string",
  "locale": "string",
  "profile_background_upload_url": "string",
  "card_background_upload_url": "string",
  "upload_id": 0
})
```