MCP Roblox Docs

🚀 MCP Roblox 文檔

這是一個全面的 MCP（模型上下文協議）服務器，提供完整的 Roblox 生態系統文檔。你可以通過 AI 助手查詢 API 參考、FastFlags、Open Cloud REST API、Luau 語言文檔和 DevForum 等內容。

🚀 快速開始

快速啟動（推薦）

使用此 MCP 服務器最簡單的方法是通過 uvx：

uvx mcp-roblox-docs

無需安裝和設置，直接可用！

從源代碼安裝

git clone https://github.com/nhattamgithub/mcp-roblox-docs
cd mcp-roblox-docs
uv sync
uv run mcp-roblox-docs

✨ 主要特性

• 始終保持最新：自動從 Roblox 的官方源同步數據。
• 27 種專業工具：全面覆蓋 Roblox 生態系統。
• 全文搜索：可搜索 850 多個類、35000 多個成員、14000 多個 FastFlags 和 865 個雲 API 端點。
• 數據類型和庫：包含 44 種數據類型（如 Vector3、CFrame 等）和 11 個 Luau 標準庫。
• 多語言支持：支持包括英語、印尼語、日語、韓語、中文等 15 種語言。
• DevForum 集成：通過智能緩存搜索社區討論。
• Open Cloud API：提供完整的 REST API 文檔，包括認證、參數和響應模式。
• FastFlags 參考：可搜索和探索 14000 多個引擎標誌。
• Luau 語言文檔：提供完整的語言參考和全局變量。
• 零成本：完全免費，無需 API 密鑰。
• 優化設計：採用懶加載、內存緩存和 DevForum 結果緩存。
• 快速同步：並行下載（快 7 - 10 倍）、重試邏輯和 HTTP 壓縮。

📦 安裝指南

快速啟動（推薦）

使用此 MCP 服務器最簡單的方法是通過 uvx：

uvx mcp-roblox-docs

無需安裝和設置，直接可用！

從源代碼安裝

git clone https://github.com/nhattamgithub/mcp-roblox-docs
cd mcp-roblox-docs
uv sync
uv run mcp-roblox-docs

💻 使用示例

搜索 API

用戶：如何平滑地為物體添加動畫效果？
AI：[使用 roblox_search("tween animation")]
→ TweenService、TweenBase、Tween、EasingStyle...

獲取類信息

用戶：介紹一下 TweenService
AI：[使用 roblox_get_class("TweenService")]
→ 包含 Create()、GetValue()、SmoothDamp() 方法的完整類信息
   類別：動畫，首選父級：game

檢查棄用情況

用戶：BodyPosition 是否已棄用？
AI：[使用 roblox_check_deprecated("BodyPosition")]
→ 是的，已棄用。請使用基於約束的 AlignPosition 代替。

搜索 FastFlags

用戶：哪些標誌控制物理效果？
AI：[使用 roblox_search_fflags("physics")]
→ FIntPhysicsMaxSteps、DFFlagPhysicsDebug、FFlagPhysicsOptimized...

獲取雲 API 端點

用戶：如何向主題發佈消息？
AI：[使用 roblox_search_cloud_api("publish message")]
→ POST /v1/universes/{universeId}/topics/{topic}
   認證：具有 messaging-service:publish 作用域的 API 密鑰

獲取 Luau 全局變量

用戶：Luau 有哪些內置函數？
AI：[使用 roblox_get_luau_globals()]
→ print、warn、error、typeof、select、pairs、ipairs、next...

Luau 語言文檔

用戶：Luau 中的類型註解如何工作？
AI：[使用 roblox_get_luau_topic("type-annotations")]
→ 關於類型語法、泛型、類型推斷的完整指南...

搜索 DevForum

用戶：人們如何在 Roblox 中優化內存？
AI：[使用 roblox_search_devforum("memory optimization")]
→ 相關社區討論的鏈接（緩存 1 小時）

獲取數據類型信息

用戶：如何創建一個 Vector3？
AI：[使用 roblox_get_datatype("Vector3")]
→ Vector3.new(x, y, z)、Vector3.one、Vector3.zero
   屬性：X、Y、Z、Magnitude、Unit
   方法：Cross、Dot、Lerp、Angle...

獲取庫函數

用戶：math.clamp 如何工作？
AI：[使用 roblox_get_library_function("math", "clamp")]
→ math.clamp(x, min, max): number
   返回 x 限制在 min 和 max 之間的值

📚 詳細文檔

配置

Claude Desktop

添加到你的 Claude Desktop 配置中：

• Windows：%APPDATA%\Claude\claude_desktop_config.json
• macOS：~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "roblox-docs": {
      "command": "uvx",
      "args": ["mcp-roblox-docs"]
    }
  }
}

Cursor / 其他 MCP 客戶端

{
  "mcpServers": {
    "roblox-docs": {
      "command": "uvx",
      "args": ["mcp-roblox-docs"]
    }
  }
}

或者如果你從源代碼運行：

{
  "command": "uv",
  "args": ["--directory", "/path/to/mcp-roblox-docs", "run", "mcp-roblox-docs"]
}

可用工具（共 27 個）

核心 API 工具

擴展 API 工具

FastFlags 工具

Luau 全局變量工具

Open Cloud API 工具

Luau 語言工具

數據類型工具

庫工具

MCP 資源（v3.3.0+）

資源提供基於 URI 的直接文檔訪問：

MCP 提示（v3.3.0+）

提示提供可重複使用的工作流模板：

數據源

所有數據均從免費的公共源獲取：

數據統計

支持的語言

使用 roblox_sync(language="id-id") 切換文檔語言：

• en-us - 英語（默認）
• id-id - 印尼語
• ja-jp - 日語
• ko-kr - 韓語
• zh-cn - 中文（簡體）
• zh-tw - 中文（繁體）
• de-de - 德語
• es-es - 西班牙語
• fr-fr - 法語
• it-it - 意大利語
• pt-br - 葡萄牙語（巴西）
• ru-ru - 俄語
• th-th - 泰語
• tr-tr - 土耳其語
• vi-vn - 越南語

緩存位置

數據緩存在系統的標準緩存目錄中：

• Windows：%LOCALAPPDATA%\mcp-roblox-docs\
• macOS：~/Library/Caches/mcp-roblox-docs/
• Linux：~/.cache/mcp-roblox-docs/ 當 Roblox 發佈新的 API 版本時，緩存會自動更新。

開發

# 克隆倉庫
git clone https://github.com/nhattamgithub/mcp-roblox-docs
cd mcp-roblox-docs

# 安裝依賴
uv sync

# 本地運行服務器
uv run mcp-roblox-docs

# 測試工具數量
uv run python -c "from src.server import mcp; print('工具數量:', len(mcp._tool_manager._tools))"

# 構建分發版本
uv build

# 發佈到 PyPI
uv publish

變更日誌

v3.3.0 (2026-01-25)

完整 MCP 原語實現

• 添加了 MCP 資源（5 個資源模板）：
  • roblox://class/{name} - 直接訪問類文檔
  • roblox://enum/{name} - 直接訪問枚舉值
  • roblox://datatype/{name} - 直接訪問數據類型文檔
  • roblox://library/{name} - 直接訪問庫文檔
  • roblox://luau/{topic} - 直接訪問 Luau 語言文檔
• 添加了 MCP 提示（4 個工作流模板）：
  • explain-api - 詳細解釋 Roblox API 類
  • debug-deprecation - 幫助從棄用的 API 遷移
  • code-review - 審查 Roblox Luau 代碼
  • learn-service - 瞭解 Roblox 服務
• 為同步操作添加了 2 分鐘超時
• 現在實現了所有 3 個 MCP 原語：工具、資源和提示

v3.2.0 (2026-01-25)

MCP 最佳實踐和質量改進

• 添加了 roblox_health 工具，用於獲取服務器狀態、統計信息和診斷信息
• 在所有 17 個接受用戶輸入的工具中添加了輸入驗證
• 通過 MCP_ROBLOX_DOCS_LOG_LEVEL 環境變量添加了可配置的日誌記錄
• 添加了 py.typed 標記文件以符合 PEP 561
• 改進了 DevForum 磁盤緩存，在保存時清理過期條目
• 修復了加載器中的重複正則表達式模式
• 更新了 USER_AGENT 以匹配當前版本
• 現在共有 27 個工具

v3.1.0 (2026-01-25)

開發者體驗和搜索改進

• 支持模糊搜索，容忍拼寫錯誤（例如，“Tweenservce” → “TweenService”）
• 持久化 DevForum 緩存（服務器重啟後仍保留）
• 為 roblox_search 工具添加了 fuzzy 參數（默認值：True）
• 修復了格式化器中的 TypedDict 類型提示，以提高類型安全性
• 添加了 pytest 測試套件（56 個測試用於驗證、搜索和緩存）
• 添加了開發依賴項：pytest、pytest-asyncio

v3.0.1 (2026-01-25)

• 修復了變更日誌中的年份（2025 -> 2026）

v3.0.0 (2026-01-25)

性能和可靠性發布

• 使用信號量進行並行下載（同步速度快 7 - 10 倍）
• 帶有指數退避的重試邏輯（3 次嘗試）
• 支持 HTTP 壓縮（gzip、deflate）
• 預編譯正則表達式模式（更快的解析）
• 現在可以通過 roblox_search 搜索數據類型/庫
• DevForum 速率限制（防止 429 錯誤）
• 用於安全的輸入驗證模塊

v2.1.0 (2026-01-25)

• 添加了數據類型文檔（44 種類型：Vector3、CFrame、Color3、UDim2、TweenInfo 等）
• 添加了 Luau 庫文檔（11 個庫：math、string、table、task 等）
• 添加了 5 個新工具：roblox_get_datatype、roblox_list_datatypes、roblox_get_library、roblox_get_library_function、roblox_list_libraries
• 工具數量從 21 個擴展到 26 個

v2.0.0 (2026-01-25)

• 添加了 FastFlags 支持（從 FVariables.txt 獲取 14000 多個標誌）
• 添加了 Luau 全局變量（87 個內置函數/類型）
• 添加了 Open Cloud REST API（從 openapi.json 獲取 865 個端點）
• 添加了 Luau 語言文檔（20 個主題）
• 添加了類元數據（類別、圖標、首選父級）
• 添加了 DevForum 緩存（TTL 為 1 小時）
• 增強了棄用替代方案（40 多個類、30 多個成員映射）
• 工具數量從 11 個擴展到 21 個

v1.0.1

• 初始穩定版本
• 核心 API 文檔工具
• DevForum 搜索集成
• 多語言支持

📄 許可證

本項目採用 MIT 許可證，詳情請參閱 LICENSE。

致謝

• Roblox-Client-Tracker 由 MaximumADHD 開發
• Roblox Creator Docs 由 Roblox 開發
• MCP Protocol 由 Anthropic 開發