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); }