Sketchfab MCP Server

Instructions

Implementation Reference

• index.ts:289-365 (handler)

  The main handler function for the 'sketchfab-search' tool. Validates inputs, checks for API key, instantiates SketchfabApiClient, performs search, formats results as text, and handles errors.
  async ({ query, tags, categories, downloadable, limit }) => { try { // Validate input if (!query && (!tags || tags.length === 0) && (!categories || categories.length === 0)) { return { content: [ { type: "text", text: "Please provide at least one search parameter: query, tags, or categories.", }, ], }; } // Check if API key is available if (!apiKey) { return { content: [ { type: "text", text: "No Sketchfab API key provided. Please provide an API key using the --api-key parameter or set the SKETCHFAB_API_KEY environment variable.", }, ], }; } // Create API client const client = new SketchfabApiClient(apiKey); // Search for models const searchResults = await client.searchModels({ q: query, tags, categories, downloadable, count: limit || 10, }); // Handle no results if (!searchResults.results || searchResults.results.length === 0) { return { content: [ { type: "text", text: "No models found matching your search criteria. Try different keywords or filters.", }, ], }; } // Format results const formattedResults = searchResults.results .map((model, index) => `[${index + 1}] ${model.name}\nID: ${model.uid}\nDownloadable: ${model.isDownloadable ? "Yes" : "No"}\n`) .join("\n"); return { content: [ { type: "text", text: `Found ${searchResults.results.length} models:\n\n${formattedResults}`, }, ], }; } catch (error: unknown) { const errorMessage = error instanceof Error ? error.message : String(error); return { content: [ { type: "text", text: `Error searching Sketchfab: ${errorMessage}`, }, ], }; } } );
• index.ts:283-288 (schema)

  Zod input schema defining the parameters accepted by the sketchfab-search tool.
  query: z.string().optional().describe("Text search query (e.g., \"car\", \"house\", \"character\") to find relevant models"), tags: z.array(z.string()).optional().describe("Filter by specific tags (e.g., [\"animated\", \"rigged\", \"pbr\"])"), categories: z.array(z.string()).optional().describe("Filter by categories (e.g., [\"characters\", \"architecture\", \"vehicles\"])"), downloadable: z.boolean().optional().describe("Set to true to show only downloadable models, false to show all models"), limit: z.number().optional().describe("Maximum number of results to return (1-24, default: 10)"), },
• index.ts:279-282 (registration)

  The server.tool registration call for the 'sketchfab-search' tool, specifying name, description, input schema, and handler function.
  server.tool( "sketchfab-search", "Search for 3D models on Sketchfab based on keywords and filters", {
• index.ts:84-131 (helper)

  The searchModels method in SketchfabApiClient class, which performs the HTTP request to Sketchfab's search endpoint and returns model results. Called by the tool handler.
  async searchModels(options: { q?: string; tags?: string[]; categories?: string[]; downloadable?: boolean; count?: number; }): Promise<{ results: SketchfabModel[]; next?: string; previous?: string; }> { try { const { q, tags, categories, downloadable, count = 24 } = options; // Build query parameters const params: Record<string, any> = { type: "models" }; if (q) params.q = q; if (tags?.length) params.tags = tags; if (categories?.length) params.categories = categories; if (downloadable !== undefined) params.downloadable = downloadable; if (count) params.count = Math.min(count, 24); // API limit is 24 // Make API request const response = await axios.get(`${SketchfabApiClient.API_BASE}/search`, { params, headers: this.getAuthHeader(), }); return { results: response.data.results || [], next: response.data.next, previous: response.data.previous, }; } catch (error: unknown) { if (axios.isAxiosError(error) && error.response) { const status = error.response.status; if (status === 401) { throw new Error("Invalid Sketchfab API key"); } else if (status === 429) { throw new Error("Sketchfab API rate limit exceeded. Try again later."); } throw new Error(`Sketchfab API error (${status}): ${error.message}`); } throw error instanceof Error ? error : new Error(String(error)); } }
• index.ts:36-67 (schema)

  TypeScript interface defining the structure of a Sketchfab model object used throughout the codebase for type safety.
  interface SketchfabModel { uid: string; name: string; description?: string; viewerUrl?: string; thumbnails?: { images?: Array<{ url: string; width: number; height: number; }>; }; user?: { username: string; displayName?: string; }; isDownloadable: boolean; downloadCount?: number; viewCount?: number; likeCount?: number; license?: string; createdAt?: string; faceCount?: number; vertexCount?: number; tags?: Array<{ slug: string; }>; categories?: Array<{ name: string; slug: string; }>; }