Vrchat MCP

1![VRChat MCP](./eyecatch.jpg)
2 
3[![npm version](https://badge.fury.io/js/vrchat-mcp.svg)](https://badge.fury.io/js/vrchat-mcp) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
4 
5[日本語](./README.ja.md) | [한국어](./README.ko.md)
6 
7This project is a Model Context Protocol (MCP) server for interacting with the VRChat API. It allows you to retrieve various information from VRChat using a standardized protocol.
8 
9<a href="https://youtu.be/0MRxhzlFCkw">
10  <img width="300" src="https://github.com/user-attachments/assets/85c00cc4-46b3-4f66-ab36-bf2891fdb283" alt="YouTube" />
11</a>
12 
13<a href="https://glama.ai/mcp/servers/u763zoyi5a">
14  <img width="380" height="200" src="https://glama.ai/mcp/servers/u763zoyi5a/badge" />
15</a>
16 
17## Overview
18 
19The VRChat MCP server provides a way to access VRChat's API endpoints in a structured manner. It supports a wide range of functionalities, including user authentication, retrieving user and friend information, accessing avatar and world data, and more.
20 
21## Usage
22 
23To start the server, ensure you have the necessary environment variables set:
24 
25```bash
26export VRCHAT_USERNAME=your_username
27export VRCHAT_AUTH_TOKEN=your_auth_token
28```
29 
30> [!NOTE]
31> #### How to obtain AUTH TOKEN
32>
33> You can use the following command to login and obtain an auth token:
34> ```
35> $ npx vrchat-auth-token-checker
36>
37> VRChat Username: your-username
38> Password: ********
39>
40> # If 2FA is enabled
41> 2FA Code: 123456
42>
43> # Success output
44> Auth Token: authcookie-xxxxx
45> ```
46> [Command source code](https://github.com/sawa-zen/vrchat-auth-token-checker)
47>
48> **Please handle the obtained token with care as it has a very long lifetime**
49 
50Then, run the following command:
51 
52```bash
53npx vrchat-mcp
54```
55 
56This will launch the MCP server, allowing you to interact with the VRChat API through the defined tools.
57 
58## Usage with Claude Desktop
59 
60To use this MCP server with Claude Desktop, you do not need to run `npx vrchat-mcp` manually. Instead, add the following configuration to your Claude Desktop config file:
61 
62- MacOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
63- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
64 
65```json
66{
67  "mcpServers": {
68    "vrchat-mcp": {
69      "command": "npx",
70      "args": ["vrchat-mcp"],
71      "env": {
72        "VRCHAT_USERNAME": "your-username",
73        "VRCHAT_AUTH_TOKEN": "your-auth-token"
74      }
75    }
76  }
77}
78```
79 
80Then, start Claude Desktop as usual. If you have to use nodenv or nvm, you may need to specify the full path to the `npx` command.
81 
82## Available Tools
83 
84This Model Context Protocol server provides the following VRChat-related tools:
85 
86### User Related
87- vrchat_get_friends_list: Get a list of friends
88- vrchat_send_friend_request: Send a friend request
89 
90### Avatar Related
91- vrchat_search_avatars: Search for avatars
92- vrchat_select_avatar: Select and switch to a specific avatar
93 
94### World Related
95- vrchat_search_worlds: Search for worlds
96- vrchat_list_favorited_worlds: Get a list of favorited worlds
97 
98### Instance Related
99- vrchat_create_instance: Create a new instance
100- vrchat_get_instance: Get information about a specific instance
101 
102### Group Related
103- vrchat_search_groups: Search for groups
104- vrchat_join_group: Join a group
105 
106### Favorites Related
107- vrchat_list_favorites: Get a list of favorites
108- vrchat_add_favorite: Add a new favorite
109- vrchat_list_favorite_groups: Get a list of favorite groups
110 
111### Invite Related
112- vrchat_list_invite_messages: Get a list of invite messages
113- vrchat_request_invite: Request an invite
114- vrchat_get_invite_message: Get a specific invite message
115 
116### Notification Related
117- vrchat_get_notifications: Get a list of notifications
118 
119## Debugging
120 
121First, build the project:
122 
123```bash
124npm install
125npm run build
126```
127 
128Since MCP servers run over stdio, debugging can be challenging. For the best debugging experience, we strongly recommend using the MCP Inspector.
129 
130You can launch the MCP Inspector via npm with this command:
131 
132```bash
133npx @modelcontextprotocol/inspector "./dist/main.js"
134```
135 
136Be sure that environment variables are properly configured.
137 
138Upon launching, the Inspector will display a URL that you can access in your browser to begin debugging.
139 
140## Publishing
141 
142To publish a new version of the package, follow these steps:
143 
1441. Pull the latest code from the main branch
145   ```bash
146   git checkout main
147   git pull origin main
148   ```
149 
1502. Build the package
151   ```bash
152   npm run build
153   ```
154 
1554. Publish to npm
156   ```bash
157   npm publish
158   ```
159 
1605. Push changes to the remote repository
161   ```bash
162   git push origin main --tags
163   ```
164 
165## Contributing
166 
167Contributions are welcome! Please fork the repository and submit a pull request for any improvements or bug fixes.
168 
169## License
170 
171This project is licensed under the MIT License. See the LICENSE file for details.
172