LottieFiles MCP Server for Animation Search

Overview

LottieFiles MCP Server is a lightweight Model Context Protocol (MCP) server that exposes search and retrieval tools for Lottie animations hosted on LottieFiles. It lets developer tools, chat assistants, and automation pipelines query animation metadata, fetch popular items, and retrieve details for embedding or previewing animations—all through a small, predictable MCP interface.

This server is useful when you want to integrate Lottie animation discovery into editor plugins, chatbots, or content pipelines without embedding the full LottieFiles UI. The MCP tools return structured animation metadata (IDs, titles, thumbnails, URLs and basic metadata) so callers can display lists, previews, or programmatically select animations for further processing.

Features

• Search Lottie animations by keyword
• Retrieve detailed metadata for a specific animation
• Fetch lists of currently popular animations
• Lightweight MCP-compatible server that integrates with MCP clients (Smithery, Claude Desktop, custom MCP clients)
• Simple local install and run with Node/npm

Installation / Configuration

Install via Smithery (automatic client wiring for Claude Desktop):

npx -y smithery install mcp-server-lottiefiles --client claude

Manual install and run:

# clone the repo
git clone https://github.com/junmer/mcp-server-lottiefiles.git
cd mcp-server-lottiefiles

# install dependencies
npm install

# build (if required) and start
npm run build
npm start

When started, the server prints the listening address and port. Replace PORT in examples below with whatever is printed by the server.

Build for development:

npm run build
npm start

No special credentials are required for basic search and metadata retrieval; however, if you plan to deploy this server publicly or integrate with rate-limited APIs, secure and rate-limit the endpoint appropriately.

Available Tools

The MCP server exposes three primary tools. Each tool returns JSON objects describing Lottie animations.

Typical parameter defaults: page = 1, limit = 20.

Tool: searchAnimations

Request example (MCP-style JSON payload):

{
  "tool": "searchAnimations",
  "params": { "query": "loading spinner", "page": 1, "limit": 10 }
}

Typical response shape:

{
  "items": [
    {
      "id": "12345",
      "title": "Loading Spinner",
      "thumbnail": "https://...",
      "url": "https://lottiefiles.com/12345-loading-spinner",
      "tags": ["loader", "spinner"],
      "duration": 1200
    }
    /* ... */
  ],
  "page": 1,
  "limit": 10,
  "total": 256
}

Tool: getAnimationDetails

Request example:

{
  "tool": "getAnimationDetails",
  "params": { "id": "12345" }
}

Typical response:

{
  "id": "12345",
  "title": "Loading Spinner",
  "author": "AnimatorName",
  "thumbnail": "https://...",
  "preview_url": "https://assets.lottiefiles.com/12345.json",
  "download_urls": {
    "json": "https://assets.lottiefiles.com/12345.json",
    "zip": "https://assets.lottiefiles.com/12345.zip"
  },
  "tags": ["loader", "spinner"],
  "width": 512,
  "height": 512,
  "duration": 1200,
  "description": "A compact loading spinner animation."
}

Tool: getPopularAnimations

Request example:

{
  "tool": "getPopularAnimations",
  "params": { "page": 1, "limit": 20 }
}

Response follows the same list structure as searchAnimations, sorted by popularity or trending rank.

Example: calling the MCP server (HTTP wrapper)

If you have an HTTP wrapper around the MCP server, you can POST a JSON payload to the server. Example using fetch (Node / browser):

const res = await fetch('http://localhost:PORT/mcp', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    tool: 'searchAnimations',
    params: { query: 'rocket', page: 1, limit: 5 }
  })
});
const data = await res.json();
console.log(data.items);

Replace PORT with the value printed by npm start or your deployed port.

Use Cases

• Editor plugin: provide an “Insert Lottie” dialog inside a design tool that queries searchAnimations for user-entered keywords, previews thumbnails, and inserts the selected animation’s JSON URL.
• Chat assistant: in a chatbot or assistant, use searchAnimations to suggest animations in response to user queries, then fetch preview_url with getAnimationDetails to render a live preview inside the chat UI.
• Content pipeline: during automated content generation, pick a suitable animation via searchAnimations, download JSON via download_urls.json and programmatically embed or convert the animation into a video or GIF asset.
• Trending display: use getPopularAnimations to build a “Trending Animations” section in an app or dashboard that showcases popular Lottie assets.

Development & Contribution

• Code is standard Node.js; run npm install and npm run build for local development.
• Tests and linting should be added or extended based on your integration requirements.
• The project is MIT-licensed; contributions and