WebSim

You can use the WebSim MCP Server to access WebSim’s public API through a standardized MCP interface. It exposes projects, users, feeds, assets, and comments in a consistent set of tools, with built‑in health checks, validation, and pagination to help you build reliable integrations with ease.

How to use

You interact with the MCP server through an MCP client. Start by running the local MCP server as shown in the installation steps, then configure your MCP client to point at the server. Use the available tools to query projects, users, feeds, assets, and comments. When you request data, you can rely on input validation to ensure your parameters are correct, and you’ll receive structured responses with pagination support for large datasets. If you hit API limits or encounter transient errors, the server provides automatic retry logic and clear error messages to help you recover gracefully.

How to install

Prerequisites: you need Node.js 18.0.0 or higher and npm or yarn.

1. Clone or download the server code.

# If using from source
git clone https://github.com/minimax/websim-mcp-server.git
cd websim-mcp-server

2. Install dependencies.

npm install

3. Run the server.

npm start

Configuration and runtime setup

Environment variables and startup configuration are designed to be straightforward. The server expects and documents the following values to tailor its behavior and connect to the WebSim public API.

Environment variables to configure your runtime (examples shown as placeholders):

• WEBSIM_API_BASE_URL=https://api.websim.com
• WEBSIM_API_TIMEOUT=30000
• MCP_SERVER_NAME=websim-mcp-server
• MCP_SERVER_VERSION=1.0.0
• LOG_LEVEL=info
• LOG_FORMAT=json

You can adjust these values in a .env file or your deployment environment. If you need to point to a different API endpoint, update WEBSIM_API_BASE_URL accordingly.

Example MCP client configuration (stdio) to run the server locally from a client perspective:

{
  "mcpServers": {
    "websim": {
      "command": "node",
      "args": ["/path/to/websim-mcp-server/server.js"],
      "env": {
        "WEBSIM_API_BASE_URL": "https://api.websim.com",
        "WEBSIM_API_TIMEOUT": "30000",
        "MCP_SERVER_NAME": "websim-mcp-server",
        "MCP_SERVER_VERSION": "1.0.0",
        "LOG_LEVEL": "info",
        "LOG_FORMAT": "json"
      }
    }
  }
}

Security & privacy

The server does not require authentication for public WebSim endpoints and does not store user data. All API calls use HTTPS to protect data in transit. Input validation ensures parameters conform to expected formats before any API call is made.

Health monitoring and resilience

Health checks verify connectivity to the WebSim API, response time, and error rates. The system includes robust error handling, configurable timeouts, and automatic retry mechanisms to ensure stability under varying network conditions.

Troubleshooting and notes

If you encounter issues, check that your environment variables are set correctly and that the API endpoint is reachable. Review logs for timeout or rate-limit messages, and ensure your MCP client is configured with the correct server name and version. For persistent problems, verify that your Node.js version matches the prerequisites and that dependencies install without errors.

API tools available

The MCP server exposes a comprehensive set of tools to query and manipulate WebSim data. Each tool accepts specific parameters and returns structured results that you can paginate or filter as needed.

Examples and usage patterns

Use the tools to discover content, browse user profiles, and retrieve project data. Combine results with pagination to build dashboards or automation workflows that respond to trending content, new assets, or community discussions.

Development and contributing

If you want to contribute improvements or new features, follow typical development practices for Node.js projects: install dependencies, run tests, and format code. The project provides scripts for development, testing, linting, and formatting to help you maintain quality.

Documentation and endpoints overview

The MCP server wraps a broad set of endpoints for projects, users, feeds, assets, and comments. You can perform actions such as retrieving a project by ID, listing public projects, searching assets, or getting user statistics. The system emphasizes input validation, pagination, and robust error handling to simplify integration.

License

MIT License - see the LICENSE file for details.

Available tools

get_project_by_id

Get project by ID with details such as metadata and revisions.

get_project_by_slug

Get a project by user and slug, returning the project data.

list_all_projects

List all public projects with optional pagination.

list_user_projects

List projects for a specific user with optional pagination.

get_project_revisions

Retrieve historical versions of a project.

get_project_stats

Get detailed statistics for a project.

get_project_descendants

Find projects derived from a given project.

get_user

Get the profile information for a user.

get_user_stats

Get activity and engagement metrics for a user.

search_users

Search users by username or criteria.

get_user_following

Get the list of users followed by a user.

get_user_followers

Get the list of followers for a user.

get_trending_feed

Get trending projects and content.

get_posts_feed

Get the latest posts and activity.

search_feed

Search the feed with sorting options like trending or newest.

get_trending_rooms

Get trending interactive rooms.

search_assets

Search for assets using a query.

bulk_asset_search

Search multiple asset queries in parallel.

search_relevant_assets

Find assets related to a query.

get_related_keywords

Get keyword suggestions for a search.

get_top_searches

Retrieve the most popular searches.

get_project_assets

Get assets within a specific project.

get_project_comments

Get comments on a project.

get_comment_replies

Get replies to a project comment.

health_check

Check API connectivity and health.