search_users
Search Gelbooru users by exact username or wildcard pattern to find specific contributors or user profiles on the image board.
Instructions
Search Gelbooru users by name or name pattern.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Exact username to search for. | |
| name_pattern | No | Wildcard username search (SQL LIKE syntax). | |
| limit | No | ||
| pid | No |
Implementation Reference
- gelbooru_mcp.py:532-537 (handler)Handler implementation for search_users tool. Constructs API parameters for Gelbooru user search, accepts name, name_pattern, limit, and pid arguments, and executes the request via _get helper.
elif name == "search_users": params = {"page": "dapi", "s": "user", "q": "index"} for key in ("name", "name_pattern", "limit", "pid"): if key in arguments: params[key] = arguments[key] result = await loop.run_in_executor(None, _get, params) - gelbooru_mcp.py:394-412 (schema)Tool schema definition for search_users. Defines the tool name, description, and input parameters including name (exact username), name_pattern (wildcard search), limit (results per page), and pid (page offset).
Tool( name="search_users", description="Search Gelbooru users by name or name pattern.", inputSchema={ "type": "object", "properties": { "name": { "type": "string", "description": "Exact username to search for.", }, "name_pattern": { "type": "string", "description": "Wildcard username search (SQL LIKE syntax).", }, "limit": {"type": "integer", "default": 20, "minimum": 1, "maximum": 100}, "pid": {"type": "integer", "default": 0}, }, }, ), - gelbooru_mcp.py:285-496 (registration)Tool registration point - the list_tools() function decorated with @server.list_tools() that returns all available tools including search_users.
@server.list_tools() async def list_tools() -> list[Tool]: return [ Tool( name="search_posts", description=( "Search Gelbooru posts by tags, page, limit, or ID. " "Supports all Gelbooru tag syntax: AND (tag1 tag2), OR ({t1~t2}), " "NOT (-tag), wildcards (*tag / tag*), meta-tags like " "rating:safe/questionable/explicit, score:>=N, width:>=N, " "user:name, sort:random, sort:score:desc, etc." ), inputSchema={ "type": "object", "properties": { "tags": { "type": "string", "description": ( "Tag query string. Examples: 'cat_ears blue_eyes', " "'touhou -rating:explicit', 'score:>=50 sort:score:desc'" ), }, "limit": { "type": "integer", "description": "Number of posts to return (default 20, max 100).", "default": 20, "minimum": 1, "maximum": 100, }, "pid": { "type": "integer", "description": "Page number (0-indexed).", "default": 0, }, "id": { "type": "integer", "description": "Fetch a single post by its Gelbooru ID.", }, "cid": { "type": "integer", "description": "Fetch posts by change ID (Unix timestamp).", }, }, }, ), Tool( name="get_deleted_posts", description=( "Retrieve deleted posts. Pass last_id to get everything deleted " "above that post ID." ), inputSchema={ "type": "object", "properties": { "last_id": { "type": "integer", "description": "Return deleted posts whose ID is above this value.", }, "limit": {"type": "integer", "default": 20, "minimum": 1, "maximum": 100}, }, }, ), Tool( name="search_tags", description=( "Search Gelbooru tags by name, pattern, or ID. " "Useful for autocomplete, tag counts, and tag type lookup." ), inputSchema={ "type": "object", "properties": { "name": { "type": "string", "description": "Exact tag name to look up.", }, "names": { "type": "string", "description": "Space-separated list of tag names, e.g. 'cat dog fox'.", }, "name_pattern": { "type": "string", "description": ( "Wildcard tag search using SQL LIKE syntax. " "Use % for multi-char wildcard, _ for single-char. " "Example: '%choolgirl%'" ), }, "id": { "type": "integer", "description": "Look up a tag by its database ID.", }, "after_id": { "type": "integer", "description": "Return tags whose ID is greater than this value.", }, "limit": {"type": "integer", "default": 20, "minimum": 1, "maximum": 100}, "order": { "type": "string", "enum": ["ASC", "DESC"], "description": "Sort direction.", }, "orderby": { "type": "string", "enum": ["date", "count", "name"], "description": "Field to sort by.", }, }, }, ), Tool( name="search_users", description="Search Gelbooru users by name or name pattern.", inputSchema={ "type": "object", "properties": { "name": { "type": "string", "description": "Exact username to search for.", }, "name_pattern": { "type": "string", "description": "Wildcard username search (SQL LIKE syntax).", }, "limit": {"type": "integer", "default": 20, "minimum": 1, "maximum": 100}, "pid": {"type": "integer", "default": 0}, }, }, ), Tool( name="get_comments", description="Retrieve comments for a specific Gelbooru post.", inputSchema={ "type": "object", "properties": { "post_id": { "type": "integer", "description": "The post ID whose comments you want to retrieve.", }, }, "required": ["post_id"], }, ), Tool( name="get_character_tags", description=( "Given a character name (e.g. 'misty_(pokemon)'), fetches the top " "highest-scored general/solo posts across multiple pages and returns " "the most frequently occurring tags split into three semantic buckets: " "eye colour/shape, hair colour/style, and other character traits. " "Each tag includes a frequency score. Results are cached to disk for 24 hours." ), inputSchema={ "type": "object", "properties": { "character_name": { "type": "string", "description": ( "The Gelbooru tag for the character, e.g. 'misty_(pokemon)', " "'rem_(re:zero)', 'saber_(fate)'. Use underscores as Gelbooru does." ), }, "max_images": { "type": "integer", "description": ( "How many top-scored posts to analyse across all pages " "(default 300). More images = slower but more reliable results. " "Fetched in pages of 100." ), "default": 300, "minimum": 10, }, }, "required": ["character_name"], }, ), Tool( name="build_prompt", description=( "Given a character name, returns a ready-to-use image-generation prompt " "string like 'misty (pokemon), green eyes, orange hair, side ponytail, ...'. " "Internally calls get_character_tags with caching, then assembles the prompt " "with tags ordered by frequency (eye → hair → other)." ), inputSchema={ "type": "object", "properties": { "character_name": { "type": "string", "description": ( "The Gelbooru tag for the character, e.g. 'misty_(pokemon)'. " "Use underscores as Gelbooru does." ), }, "max_images": { "type": "integer", "description": "Posts to analyse (default 300). Cached after first fetch.", "default": 300, "minimum": 10, }, "include_other": { "type": "boolean", "description": ( "Whether to include non-eye/hair tags (clothing, accessories, etc.) " "in the prompt. Default true." ), "default": True, }, }, "required": ["character_name"], }, ), ] - gelbooru_mcp.py:44-59 (helper)Helper function _get used by search_users handler. Performs synchronous HTTP GET requests to Gelbooru API, handles authentication, and returns parsed JSON response.
def _get(params: dict) -> Any: """Perform a synchronous HTTP GET and return parsed JSON.""" params = {**params, "json": "1"} # copy — never mutate the caller's dict _build_auth(params) url = f"{BASE_URL}?{urlencode(params)}" req = Request(url, headers={"User-Agent": "GelbooruMCP/1.0"}) try: with urlopen(req, timeout=15) as resp: raw = resp.read().decode("utf-8") except URLError as exc: return {"error": str(exc)} try: return json.loads(raw) except json.JSONDecodeError: # Some endpoints return XML/empty on error; surface the raw text return {"raw": raw}