Civitai MCP Server

Instructions

Implementation Reference

• src/index.ts:499-520 (handler)

  The handler function that implements the core logic for the 'browse_images' tool. It invokes the CivitaiClient to fetch images and formats a detailed text response listing image details including IDs, creators, dimensions, NSFW levels, reactions, URLs, and generation info.

  private async browseImages(args: any) {
    const response = await this.client.getImages(args);
    
    return {
      content: [
        {
          type: 'text',
          text: `Found ${response.metadata.totalItems || response.items.length} images:\\n\\n${response.items.map(image => 
            `**Image ID:** ${image.id}\\n` +
            `**Creator:** ${image.username || 'Unknown'}\\n` +
            `**Dimensions:** ${image.width}x${image.height}\\n` +
            `**NSFW Level:** ${image.nsfwLevel || 'Unknown'}\\n` +
            `**Reactions:** ❤️ ${image.stats?.heartCount || 0} | 👍 ${image.stats?.likeCount || 0} | 💬 ${image.stats?.commentCount || 0}\\n` +
            `**URL:** ${image.url}\\n` +
            `**Created:** ${image.createdAt ? new Date(image.createdAt).toLocaleDateString() : 'Unknown'}\\n` +
            (image.meta ? `**Generation Info:** ${JSON.stringify(image.meta, null, 2).substring(0, 200)}...\\n` : '') +
            '\\n'
          ).join('---\\n')}\\nPage ${response.metadata.currentPage || 1}`,
        },
      ],
    };
  }

• src/index.ts:167-192 (schema)

  Input schema defining the parameters for the 'browse_images' tool, including limits, pagination, filters for models, versions, posts, users, NSFW levels, sorting, and periods.

  inputSchema: {
    type: 'object',
    properties: {
      limit: { type: 'number', description: 'Number of images to return (1-200, default 100)', minimum: 1, maximum: 200 },
      page: { type: 'number', description: 'Page number for pagination', minimum: 1 },
      modelId: { type: 'number', description: 'Filter images from a specific model' },
      modelVersionId: { type: 'number', description: 'Filter images from a specific model version' },
      postId: { type: 'number', description: 'Get images from a specific post' },
      username: { type: 'string', description: 'Filter images by creator username' },
      nsfw: { 
        type: 'string',
        enum: ['None', 'Soft', 'Mature', 'X'],
        description: 'NSFW content level filter'
      },
      sort: {
        type: 'string',
        enum: ['Most Reactions', 'Most Comments', 'Newest'],
        description: 'Sort order for images'
      },
      period: {
        type: 'string',
        enum: ['AllTime', 'Year', 'Month', 'Week', 'Day'],
        description: 'Time period for sorting'
      }
    },
  },

• src/index.ts:57-58 (registration)

  Registration of the 'browse_images' handler in the main tool dispatch switch statement within the CallToolRequestSchema handler.

  case 'browse_images':
    return await this.browseImages(args);

• src/index.ts:164-193 (registration)

  Tool registration in the getTools() method, which provides the tool list to the MCP ListToolsRequestSchema, including name, description, and input schema.

  {
    name: 'browse_images',
    description: 'Browse AI-generated images from Civitai',
    inputSchema: {
      type: 'object',
      properties: {
        limit: { type: 'number', description: 'Number of images to return (1-200, default 100)', minimum: 1, maximum: 200 },
        page: { type: 'number', description: 'Page number for pagination', minimum: 1 },
        modelId: { type: 'number', description: 'Filter images from a specific model' },
        modelVersionId: { type: 'number', description: 'Filter images from a specific model version' },
        postId: { type: 'number', description: 'Get images from a specific post' },
        username: { type: 'string', description: 'Filter images by creator username' },
        nsfw: { 
          type: 'string',
          enum: ['None', 'Soft', 'Mature', 'X'],
          description: 'NSFW content level filter'
        },
        sort: {
          type: 'string',
          enum: ['Most Reactions', 'Most Comments', 'Newest'],
          description: 'Sort order for images'
        },
        period: {
          type: 'string',
          enum: ['AllTime', 'Year', 'Month', 'Week', 'Day'],
          description: 'Time period for sorting'
        }
      },
    },
  },

• src/civitai-client.ts:139-142 (helper)

  Supporting helper method in CivitaiClient that performs the actual API request to Civitai's /images endpoint using the provided parameters and validates the response with ImagesResponseSchema.

  async getImages(params: ImagesParams = {}): Promise<ImagesResponse> {
    const url = this.buildUrl('/images', params);
    return this.makeRequest<ImagesResponse>(url, ImagesResponseSchema);
  }