Bridging Worlds: VRChat API Integration with the Model Context Protocol (MCP)

Unlock the potential of VRChat data within your AI applications using the VRChat MCP server. This open-source project provides a standardized interface for accessing a wealth of VRChat information, empowering you to build intelligent and context-aware experiences.

Overview: Seamless VRChat Data Access

The VRChat MCP server acts as a bridge between the VRChat API and the Model Context Protocol. This allows you to retrieve and utilize VRChat data, such as user profiles, friend lists, avatar details, and world information, in a structured and consistent manner within your LLM-powered applications.

Getting Started: Connecting to VRChat

Prerequisites

Before launching the server, ensure you have the following environment variables configured:

export VRCHAT_USERNAME=your_username
export VRCHAT_PASSWORD=your_password
export VRCHAT_TOTP_SECRET=your_totp_secret
export VRCHAT_EMAIL=[email protected]

Important Security Note:

[!WARNING]

TOTP Secret Acquisition

Obtaining your TOTP secret involves extracting it from the QR code displayed when enabling Two-Factor Authentication on the VRChat website. This method carries inherent security risks. Exercise extreme caution and consider the implications before proceeding.

Launching the Server

With the environment variables set, initiate the MCP server using the following command:

npx vrchat-mcp

This command starts the server, enabling you to interact with the VRChat API through the MCP interface.

Integration with Claude Desktop: Streamlined Workflow

For users of Claude Desktop, manual server execution is unnecessary. Integrate the VRChat MCP server directly by adding the following configuration to your Claude Desktop config file:

• MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
    "mcpServers": {
        "vrchat-mcp": {
            "command": "npx",
            "args": ["vrchat-mcp"],
            "env": {
                "VRCHAT_USERNAME": "your-username",
                "VRCHAT_PASSWORD": "your-password",
                "VRCHAT_TOTP_SECRET": "your-totp-secret",
                "VRCHAT_EMAIL": "[email protected]"
            }
        }
    }
}

After adding the configuration, launch Claude Desktop as usual. If you are using nodenv or nvm, ensure that the full path to the npx command is specified.

VRChat API Endpoint Support: A Comprehensive Overview

The following table outlines the VRChat API endpoints currently supported or planned for implementation within the VRChat MCP server. Both GET and POST methods are considered to provide a complete feature set.

Authentication and User Information

• Get current user info
• Search users
• Get specific user profile
• Get user groups
• Get player moderations
• Get user status
• Update user info
• Update user status
• Block user
• Unblock user

Friend Related

• Get friends list
• Get online friends
• Send friend request
• Accept/Deny friend request
• Remove friend

Avatar Related

• Get own avatars
• Get favorite avatars
• Search avatars
• Get specific avatar details
• Get public avatars
• Create avatar
• Update avatar
• Delete avatar
• Select avatar
• Favorite/Unfavorite avatar

World Related

• Get worlds list
• Get active worlds
• Get recently visited worlds
• Get favorite worlds
• Search worlds
• Get specific world details
• Get world instances
• Get public worlds
• Create world
• Update world
• Delete world
• Favorite/Unfavorite world

Instance Related

• Create instance
• Get instance info
• Get instance attendees
• Get instance short name
• Join instance
• Leave instance
• Invite user to instance

File Related

• Get file info
• Get file download info
• Get file status

Group Related

• Search groups
• Get specific group info
• Get group members
• Get group permissions
• Get group requests
• Get group invites
• Get group bans
• Get group galleries
• Get group owned worlds
• Create group
• Update group
• Delete group
• Join group
• Leave group
• Invite user to group
• Accept/Deny group invite
• Ban user from group
• Unban user from group

Notification Related

• Get notifications list
• Get friend requests
• Get unread notification count
• Mark notification as read
• Delete notification
• Clear all notifications

Inventory Related

• Get license types
• Get owned licenses
• Get stores list

System Related

• Get API configuration
• Get API limits
• Check system health
• Get online users count
• Get server announcements

Favorites

• List Favorites
• Add Favorite
• Remove Favorite
• List Favorite Groups
• Show Favorite Group
• Update Favorite Group
• Clear Favorite Group
• Get Favorite Limits

Invites

• List Invite Messages
• Request Invite
• Send Invite
• Get Invite Message
• Update Invite Message

Others

• Get tags list
• Get invisibles list
• Get moderations
• Get favorite group types
• Create moderation
• Delete moderation

Debugging: Ensuring Robustness

Debugging MCP servers that operate over stdio can be complex. For an optimal debugging experience, the MCP Inspector is highly recommended.

1. Build the Project:

   npm install
   npm run build

2. Launch the MCP Inspector:

   npx @modelcontextprotocol/inspector "./dist/main.js"

   Ensure that all necessary environment variables are correctly configured before launching the inspector.

The Inspector will provide a URL to access a browser-based debugging interface.

Contributing: Shaping the Future

We encourage contributions to enhance the VRChat MCP server. Fork the repository and submit pull requests to contribute improvements and bug fixes.