Civitai MCP Server

Instructions

Implementation Reference

• src/index.ts:400-418 (handler)

  The main handler function for the 'search_models' tool. It calls the CivitaiClient's getModels method with the provided arguments, formats the response, and returns a formatted text response for the MCP protocol.

  private async searchModels(args: any) {
    const response = await this.client.getModels(args);
    const formatted = this.formatModelsResponse(response);
    
    return {
      content: [
        {
          type: 'text',
          text: `Found ${formatted.pagination.totalItems} models:\\n\\n${formatted.models.map((model: any) => 
            `**${model.name}** (${model.type})\\n` +
            `Creator: ${model.creator}\\n` +
            `Downloads: ${model.stats.downloads.toLocaleString()} | Rating: ${model.stats.rating.toFixed(1)}\\n` +
            `Tags: ${model.tags.join(', ')}\\n` +
            `${model.description}\\n`
          ).join('\\n---\\n')}\\n\\nPage ${formatted.pagination.currentPage} of ${formatted.pagination.totalPages}`,
        },
      ],
    };
  }

• src/index.ts:96-130 (schema)

  Tool schema definition including input schema with properties for query, limit, page, types, sort, period, nsfw, and baseModels.

    name: 'search_models',
    description: 'Search for AI models on Civitai with various filters',
    inputSchema: {
      type: 'object',
      properties: {
        query: { type: 'string', description: 'Search query to filter models by name' },
        limit: { type: 'number', description: 'Number of results (1-100, default 20)', minimum: 1, maximum: 100 },
        page: { type: 'number', description: 'Page number for pagination', minimum: 1 },
        types: { 
          type: 'array', 
          items: { 
            type: 'string',
            enum: ['Checkpoint', 'TextualInversion', 'Hypernetwork', 'AestheticGradient', 'LORA', 'Controlnet', 'Poses']
          },
          description: 'Filter by model types'
        },
        sort: { 
          type: 'string', 
          enum: ['Highest Rated', 'Most Downloaded', 'Newest'],
          description: 'Sort order for results'
        },
        period: {
          type: 'string',
          enum: ['AllTime', 'Year', 'Month', 'Week', 'Day'],
          description: 'Time period for sorting'
        },
        nsfw: { type: 'boolean', description: 'Include NSFW content' },
        baseModels: {
          type: 'array',
          items: { type: 'string' },
          description: 'Filter by base model types (e.g., ["SD 1.5", "SDXL 1.0"])'
        }
      },
    },
  },

• src/index.ts:49-50 (registration)

  Registration of the tool handler in the switch statement within the CallToolRequestSchema handler.

  case 'search_models':
    return await this.searchModels(args);

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

  Helper function to format the raw models response from the API into a structured 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,
      },
    };
  }

• src/civitai-client.ts:119-122 (helper)

  Core API client method called by the tool handler to fetch models from Civitai API endpoint '/models' with search parameters.

  async getModels(params: ModelsParams = {}): Promise<ModelsResponse> {
    const url = this.buildUrl('/models', params);
    return this.makeRequest<ModelsResponse>(url, ModelsResponseSchema);
  }