Civitai MCP Server

Instructions

Implementation Reference

• src/index.ts:611-628 (handler)

  The primary MCP tool handler for 'search_models_by_tag'. It invokes the CivitaiClient, formats the API response into a readable list of models, and returns it as MCP text content.

  private async searchModelsByTag(args: any) {
    const response = await this.client.searchModelsByTag(args.tag, args);
    const formatted = this.formatModelsResponse(response);
    
    return {
      content: [
        {
          type: 'text',
          text: `# Models tagged "${args.tag}"\\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` +
            `${model.description}\\n\\n`
          ).join('---\\n')}`,
        },
      ],
    };
  }

• src/index.ts:261-272 (schema)

  JSON schema defining the input parameters for the 'search_models_by_tag' tool, including required 'tag' and optional 'limit' and 'sort'.

  inputSchema: {
    type: 'object',
    properties: {
      tag: { type: 'string', description: 'Tag name to search for' },
      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: ['tag'],

• src/index.ts:258-274 (registration)

  Tool registration in the getTools() method, defining name, description, and input schema for 'search_models_by_tag' returned in ListTools response.

  {
    name: 'search_models_by_tag',
    description: 'Search for models by a specific tag',
    inputSchema: {
      type: 'object',
      properties: {
        tag: { type: 'string', description: 'Tag name to search for' },
        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: ['tag'],
    },
  },

• src/index.ts:69-70 (registration)

  Dispatch registration in the CallToolRequest handler switch statement, routing calls to the searchModelsByTag handler.

  case 'search_models_by_tag':
    return await this.searchModelsByTag(args);

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

  Helper function used by the handler to format raw API model responses into a simplified structure for display.

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