Civitai MCP Server

Instructions

Implementation Reference

• src/index.ts:540-553 (handler)

  The main MCP tool handler for 'get_tags'. Fetches tags using the CivitaiClient, formats the response into a textual MCP content block listing tags with model counts.

  private async getTags(args: any) {
    const response = await this.client.getTags(args);
    
    return {
      content: [
        {
          type: 'text',
          text: `Found ${response.metadata.totalItems || response.items.length} tags:\\n\\n${response.items.map(tag => 
            `**${tag.name}** (${tag.modelCount || 0} models)\\n`
          ).join('')}\\nPage ${response.metadata.currentPage || 1} of ${response.metadata.totalPages || 1}`,
        },
      ],
    };
  }

• src/index.ts:206-217 (registration)

  Registration of the 'get_tags' tool in the listTools response, including name, description, and input schema definition.

  {
    name: 'get_tags',
    description: 'Browse and search for model tags on Civitai',
    inputSchema: {
      type: 'object',
      properties: {
        limit: { type: 'number', description: 'Number of tags to return (1-200, default 20)', minimum: 1, maximum: 200 },
        page: { type: 'number', description: 'Page number for pagination', minimum: 1 },
        query: { type: 'string', description: 'Search query to filter tags by name' },
      },
    },
  },

• src/types.ts:138-141 (schema)

  Zod schema for validating the TagsResponse from the Civitai API, used in the client.makeRequest method.

  export const TagsResponseSchema = z.object({
    items: z.array(TagSchema),
    metadata: MetadataSchema,
  });

• src/civitai-client.ts:149-152 (helper)

  Core helper method in CivitaiClient that performs the actual API request to fetch tags from Civitai, builds URL with params, and validates response using TagsResponseSchema.

  async getTags(params: TagsParams = {}): Promise<TagsResponse> {
    const url = this.buildUrl('/tags', params);
    return this.makeRequest<TagsResponse>(url, TagsResponseSchema);
  }

• src/civitai-client.ts:63-67 (schema)

  TypeScript interface defining the input parameters for getTags, matching the inputSchema in tool registration.

  export interface TagsParams {
    limit?: number;
    page?: number;
    query?: string;
  }