MCP Server (AI Integration)

The MCP (Model Context Protocol) server for tsParticles lets AI assistants inspect the package catalog, suggest required plugins and bundles from options, diagnose configuration issues, and generate complete tsParticles code from natural language.

Quick start (local)

npx @tsparticles/mcp-server

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "tsparticles": {
      "command": "npx",
      "args": ["@tsparticles/mcp-server"]
    }
  }
}

Cursor

In Cursor settings, add a new MCP server with:

• Name: tsparticles
• Type: command
• Command: npx @tsparticles/mcp-server

Tools

Once connected, the AI assistant can use these tools:

Tool	Description
suggest_plugins	Given a tsParticles options object, returns the npm packages and imports needed
list_packages	Lists available packages, optionally filtered by category or search query
get_package_info	Returns detailed info about a specific package
diagnose_issues	Analyzes options for configuration problems and performance issues
generate_code	Generates complete code from a natural language description with smart bundle selection

Generating code

generate_code turns a natural language description into ready-to-use code. It uses deterministic keyword matching to pick the right bundle, preferring specialized bundles such as @tsparticles/confetti, @tsparticles/fireworks, and @tsparticles/ribbons over the generic ones.

generate_code({ description: "confetti on my React website", framework: "react" })

The result includes the selected bundle, the npm install command, the generated code, and the html snippet. Auto-initialized bundles ignore the framework option: @tsparticles/confetti with framework: "react" returns the load-function snippet in code (import { confetti } from "@tsparticles/confetti" plus an await confetti(...) call), not a framework component, and leaves html empty. Other bundles return the framework-specific component in code; for framework: "vanilla" code is a load script instead, and html — populated only for framework: "vanilla" — contains the container div.

Resources

The server also exposes reference resources that the AI can read:

URI	Description
tsparticles://packages	Complete package catalog by category
tsparticles://options/guide	Full options structure with defaults and examples
tsparticles://bundles	Bundle hierarchy and selection guide

Prompt

A built-in prompt template lets you generate options from natural language:

"Generate tsParticles options for a fireworks effect with colorful trails"

The AI will produce a complete tsParticles configuration.

Deploy remotely

The server can run as an HTTP endpoint for remote access.

Docker

git clone https://github.com/tsparticles/tsparticles.git
cd tsparticles/integrations/mcp-server
docker compose up -d

The server listens on http://localhost:3000/mcp.

Docker + Cloudflare Tunnel (public HTTPS)

docker compose --profile tunnel up

This prints a temporary public URL like https://random.trycloudflare.com. Use https://random.trycloudflare.com/mcp as the endpoint in your MCP client.

Docker + Synology NAS

If you have a Synology NAS, use the Reverse Proxy in DSM:

1. Run docker compose up -d on the NAS
2. Go to Control Panel > Application Portal > Reverse Proxy
3. Create a rule: source https://your-nas-domain:8443 → destination http://localhost:3000
4. Your endpoint will be https://your-nas-domain:8443/mcp

Client configuration for remote access

When connecting to a remote server, the MCP client needs the endpoint URL:

https://your-server.com/mcp

Claude Desktop (remote)

{
  "mcpServers": {
    "tsparticles": {
      "command": "npx",
      "args": ["@tsparticles/mcp-server"]
    }
  }
}

For the stdio transport, the server runs locally. For HTTP transport, follow the client's documentation for configuring SSE-based MCP servers.