Noun Project MCP Server

Instructions

Implementation Reference

• src/api.ts:65-85 (handler)

  Core handler function that executes the search_icons tool by constructing query parameters, generating OAuth headers, and making an HTTP GET request to the Noun Project API's icon search endpoint.

  async searchIcons(params: SearchIconsParams) {
    const { query, ...rest } = params;
    const queryParams = new URLSearchParams({
      query,
      ...Object.fromEntries(
        Object.entries(rest)
          .filter(([_, v]) => v !== undefined)
          .map(([k, v]) => [k, String(v)])
      ),
    });
  
    const url = `${BASE_URL}/v2/icon?${queryParams}`;
    const headers = this.oauth.getHeaders(url);
  
    const response = await this.client.get('/v2/icon', {
      params: Object.fromEntries(queryParams),
      headers,
    });
  
    return response.data;
  }

• src/api.ts:6-16 (schema)

  TypeScript interface defining the input parameters for the searchIcons function, matching the Noun Project API query parameters.

  export interface SearchIconsParams {
    query: string;
    styles?: 'solid' | 'line' | 'solid,line';
    line_weight?: number | string;
    limit_to_public_domain?: 0 | 1;
    thumbnail_size?: 42 | 84 | 200;
    include_svg?: 0 | 1;
    limit?: number;
    next_page?: string;
    prev_page?: string;
  }

• src/tools.ts:4-48 (registration)

  MCP tool registration object defining the 'search_icons' tool, including name, description, and detailed inputSchema for validation.

  {
    name: 'search_icons',
    description:
      'Search for icons on The Noun Project. Supports filtering by style (solid/line), line weight, public domain status, and more.',
    inputSchema: {
      type: 'object',
      properties: {
        query: {
          type: 'string',
          description: 'Search term for icons (e.g., "dog", "house", "bicycle")',
        },
        styles: {
          type: 'string',
          enum: ['solid', 'line', 'solid,line'],
          description:
            'Filter by icon style: solid, line, or both (solid,line)',
        },
        line_weight: {
          type: ['number', 'string'],
          description:
            'For line icons, filter by line weight (1-60) or range (e.g., "18-20")',
        },
        limit_to_public_domain: {
          type: 'number',
          enum: [0, 1],
          description: 'Set to 1 to limit results to public domain icons only',
        },
        thumbnail_size: {
          type: 'number',
          enum: [42, 84, 200],
          description: 'Thumbnail size to return (42, 84, or 200 pixels)',
        },
        include_svg: {
          type: 'number',
          enum: [0, 1],
          description: 'Set to 1 to include SVG URLs in the response',
        },
        limit: {
          type: 'number',
          description: 'Maximum number of results to return',
        },
      },
      required: ['query'],
    },
  },

• src/index.ts:54-64 (handler)

  MCP server request handler dispatch case that invokes the api.searchIcons method and formats the response as MCP content.

  case 'search_icons': {
    const result = await api.searchIcons(args as any);
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify(result, null, 2),
        },
      ],
    };
  }

• src/tools.ts:8-47 (schema)

  JSON Schema for input validation used in MCP tool registration for search_icons.

  inputSchema: {
    type: 'object',
    properties: {
      query: {
        type: 'string',
        description: 'Search term for icons (e.g., "dog", "house", "bicycle")',
      },
      styles: {
        type: 'string',
        enum: ['solid', 'line', 'solid,line'],
        description:
          'Filter by icon style: solid, line, or both (solid,line)',
      },
      line_weight: {
        type: ['number', 'string'],
        description:
          'For line icons, filter by line weight (1-60) or range (e.g., "18-20")',
      },
      limit_to_public_domain: {
        type: 'number',
        enum: [0, 1],
        description: 'Set to 1 to limit results to public domain icons only',
      },
      thumbnail_size: {
        type: 'number',
        enum: [42, 84, 200],
        description: 'Thumbnail size to return (42, 84, or 200 pixels)',
      },
      include_svg: {
        type: 'number',
        enum: [0, 1],
        description: 'Set to 1 to include SVG URLs in the response',
      },
      limit: {
        type: 'number',
        description: 'Maximum number of results to return',
      },
    },
    required: ['query'],
  },