Civitai MCP Server

Instructions

Implementation Reference

• src/index.ts:649-666 (handler)

  Main handler function for the 'get_models_by_type' tool. It calls the CivitaiClient's getModelsByType method, formats the response using formatModelsResponse, and returns a formatted text content block.

  private async getModelsByType(args: any) {
    const response = await this.client.getModelsByType(args.type, args);
    const formatted = this.formatModelsResponse(response);
    
    return {
      content: [
        {
          type: 'text',
          text: `# ${args.type} Models\\n\\n${formatted.models.map((model: any) => 
            `**${model.name}**\\n` +
            `Creator: ${model.creator}\\n` +
            `Downloads: ${model.stats.downloads.toLocaleString()} | Rating: ${model.stats.rating.toFixed(1)}\\n` +
            `${model.description}\\n\\n`
          ).join('---\\n')}`,
        },
      ],
    };
  }

• src/index.ts:292-312 (registration)

  Tool registration in the getTools() method, including name, description, and input schema definition.

  {
    name: 'get_models_by_type',
    description: 'Get models filtered by type (Checkpoint, LORA, etc.)',
    inputSchema: {
      type: 'object',
      properties: {
        type: { 
          type: 'string',
          enum: ['Checkpoint', 'TextualInversion', 'Hypernetwork', 'AestheticGradient', 'LORA', 'Controlnet', 'Poses'],
          description: 'Model type to filter by'
        },
        limit: { type: 'number', description: 'Number of models to return (default: 20)', minimum: 1, maximum: 100 },
        sort: { 
          type: 'string', 
          enum: ['Highest Rated', 'Most Downloaded', 'Newest'],
          description: 'Sort order for results'
        },
      },
      required: ['type'],
    },
  },

• src/index.ts:295-311 (schema)

  Input schema definition for the tool, specifying required 'type' parameter and optional limit/sort.

  inputSchema: {
    type: 'object',
    properties: {
      type: { 
        type: 'string',
        enum: ['Checkpoint', 'TextualInversion', 'Hypernetwork', 'AestheticGradient', 'LORA', 'Controlnet', 'Poses'],
        description: 'Model type to filter by'
      },
      limit: { type: 'number', description: 'Number of models to return (default: 20)', minimum: 1, maximum: 100 },
      sort: { 
        type: 'string', 
        enum: ['Highest Rated', 'Most Downloaded', 'Newest'],
        description: 'Sort order for results'
      },
    },
    required: ['type'],
  },

• src/civitai-client.ts:172-174 (helper)

  CivitaiClient helper method that converts the single 'type' parameter to types=[type] array and delegates to getModels API call.

  async getModelsByType(type: string, options: Partial<ModelsParams> = {}): Promise<ModelsResponse> {
    return this.getModels({ types: [type], ...options });
  }

• src/index.ts:327-361 (helper)

  Helper function to format the raw API models response into a structured, readable format used by the handler.

  private formatModelsResponse(response: any) {
    const models = response.items.map((model: any) => {
      const latestVersion = model.modelVersions[0];
      return {
        id: model.id,
        name: model.name,
        type: model.type,
        creator: model.creator.username,
        description: model.description.substring(0, 200) + (model.description.length > 200 ? '...' : ''),
        tags: model.tags.slice(0, 5), // Limit tags for readability
        nsfw: model.nsfw,
        stats: {
          downloads: model.stats?.downloadCount || 0,
          rating: model.stats?.rating || 0,
          favorites: model.stats?.favoriteCount || 0,
        },
        latestVersion: latestVersion ? {
          id: latestVersion.id,
          name: latestVersion.name,
          createdAt: latestVersion.createdAt,
          trainedWords: latestVersion.trainedWords,
        } : null,
      };
    });
  
    return {
      models,
      pagination: {
        currentPage: response.metadata.currentPage || 1,
        totalPages: response.metadata.totalPages || 1,
        totalItems: response.metadata.totalItems || models.length,
        hasNextPage: response.metadata.nextPage ? true : false,
      },
    };
  }