如何在通義靈碼里使用 MCP 能力？

本文介紹了如何使用 MCP（模型上下文協(xié)議）服務(wù)擴(kuò)展通義靈碼功能的綜合指南，涵蓋從服務(wù)配置到實(shí)際應(yīng)用的場景示例。

通義靈碼編程智能體支持 MCP 工具使用，根據(jù)用戶需求描述，通過模型自主規(guī)劃，實(shí)現(xiàn) MCP 工具調(diào)用，并深度集成國內(nèi)最大的 MCP 中文社區(qū)——魔搭 MCP 廣場，涵蓋開發(fā)者工具、文件系統(tǒng)、搜索、地圖等十大熱門領(lǐng)域 2400+ MCP 服務(wù)，全面拓寬 AI 編碼助手能力邊界，更加貼合開發(fā)者工作流程。

重要

本文中含有需要您注意的重要提示信息，忽略該信息可能對您的業(yè)務(wù)造成影響，請務(wù)必仔細(xì)閱讀。

本文介紹了如何使用 MCP（模型上下文協(xié)議）服務(wù)擴(kuò)展通義靈碼功能的綜合指南，涵蓋從服務(wù)配置到實(shí)際應(yīng)用的場景示例。

前提條件

如需使用該功能，需要開發(fā)者將通義靈碼 IDE 端插件更新：

JetBrains 插件：插件版本更新至 v2.5.0 及以上。
VS Code 插件：插件版本更新至 v2.5.0 及以上。

下載操作可前往下載安裝。

模型上下文協(xié)議（Model Context Protocol）

MCP (Model Context Protocol)是一種開放標(biāo)準(zhǔn)協(xié)議，旨在為大語言模型（LLM）提供標(biāo)準(zhǔn)化的外部工具和上下文集成方式。借助 MCP 標(biāo)準(zhǔn)化接口的支持，通義靈碼能夠靈活擴(kuò)展與不同數(shù)據(jù)源或外部系統(tǒng)的連接，使其智能體的能力和場景得到拓展，有效滿足用戶對于個(gè)性化擴(kuò)展的訴求。

您可以選擇連接現(xiàn)有的MCP服務(wù)或自行開發(fā)專屬的 MCP 服務(wù)，例如魔搭社區(qū) MCP 市場、Higress MCP 市場等熱門市場，已經(jīng)提供了豐富的 MCP 服務(wù)，您可以自行探索發(fā)現(xiàn)更多符合您需求的解決方案，加速項(xiàng)目開發(fā)與創(chuàng)新。

通義靈碼支持兩種 MCP 服務(wù)器通信模式：

STDIO 模式：在此模式下，通信通過標(biāo)準(zhǔn)輸入輸出流進(jìn)行，服務(wù)運(yùn)行在本地。
SSE 模式：采用服務(wù)器發(fā)送事件（SSE）協(xié)議進(jìn)行通信，服務(wù)可以運(yùn)行在遠(yuǎn)端或本地。

MCP 服務(wù)配置與使用

重要

支持在智能體模式下使用 MCP 服務(wù)，配合 qwen3 模型一起使用。

允許同時(shí)連接最多 10 個(gè) MCP 服務(wù)。

添加 MCP 服務(wù)

1. 進(jìn)入 MCP 服務(wù)頁面

單擊通義靈碼歡迎語中的 MCP 工具鏈接，或在右上角頭像處進(jìn)入個(gè)人設(shè)置，單擊條形框，進(jìn)入 MCP 服務(wù)頁面。

說明

MCP 添加后，可跨本地工程和 IDE 使用。

2. 添加服務(wù)

方式一：通過 MCP 廣場完成添加

單擊MCP 廣場 標(biāo)簽，可以看到推薦的 MCP 服務(wù)列表以及魔搭社區(qū)提供的全部 MCP 服務(wù)。
在 MCP 廣場 中，瀏覽或搜索所需 MCP 服務(wù)，單擊安裝完成一鍵自動(dòng)安裝。

說明

部分 MCP Server 在運(yùn)行使用時(shí)需要額外提供環(huán)境變量，例如 API_KEY 或 ACCESS_TOKEN。

安裝完成后，返回我的服務(wù)頁面，即可看到新安裝的服務(wù)。圖標(biāo)顯示為，表示連接成功可正常使用。展開詳情，可以看到 MCP 提供的工具列表。

說明

如果命令所依賴的環(huán)境缺失，會(huì)顯示服務(wù)啟動(dòng)異常，請手動(dòng)安裝所需依賴。請參見常見問題。

方式二：通過手動(dòng)方式完成添加

在 MCP 服務(wù)頁面右上角單擊“ + ”選擇以下方式完成添加：

手工添加：
- STDIO 類型：填寫名稱、命令、參數(shù)和環(huán)境變量（選填）。
- SSE 類型： 填寫名稱和服務(wù)地址。
配置文件添加：
- 在 JSON 配置文件中增加服務(wù)對應(yīng)的JSON配置信息。

添加完成后，即可看到新安裝的服務(wù)。圖標(biāo)顯示為，表示連接成功可正常使用。展開詳情，可以看到 MCP 提供的工具列表。

使用 MCP 工具

通義靈碼會(huì)根據(jù)用戶輸入的提示詞，結(jié)合 MCP 工具的名字及描述，自動(dòng)判斷所需調(diào)用的 MCP 工具，并將工具返回的結(jié)果輸入下一步的處理流程中。

1. 輸入提示詞

在 IDE 的對話框中切換為智能體模式，并在對話框中輸入如下提示詞。

2. 執(zhí)行工具

當(dāng)通義靈碼需要調(diào)用 MCP 工具時(shí)，系統(tǒng)會(huì)出現(xiàn)提示，等您確認(rèn)后將繼續(xù)操作。

3. 查看工具執(zhí)行結(jié)果

工具執(zhí)行完成后，通義靈碼的交互窗口將顯示執(zhí)行結(jié)果。您可以展開查看 MCP 工具的詳細(xì)輸入與輸出信息，便于進(jìn)一步分析和操作。

4. 代碼審查與采納

問答交互完成后，您可審查并采納最終的代碼生成。

場景使用示例

通義靈碼支持兩種類型的 MCP 服務(wù)，您可以選擇合適的 MCP 服務(wù)類型，來體驗(yàn)通義靈碼 MCP 功能。

SSE 類型（遠(yuǎn)端服務(wù)托管） ：此類型的服務(wù)托管在遠(yuǎn)程服務(wù)器上，配置過程簡單快捷，非常適合初次接觸的新手用戶快速上手體驗(yàn)。在本示例中，您可以通過魔搭社區(qū)的 MCP 市場選用fetch MCP服務(wù)，輕松實(shí)現(xiàn)從任意網(wǎng)頁抓取內(nèi)容的能力。
STDIO 類型（本地服務(wù)運(yùn)行） ：此類型的服務(wù)在您的本地環(huán)境中運(yùn)行，需要依賴您本地環(huán)境準(zhǔn)備，適合于專業(yè)開發(fā)者。 在本示例中，您將通過體驗(yàn)使用 weather MCP 查詢城市天氣的能力。

場景一：使用遠(yuǎn)端 MCP 抓取網(wǎng)頁內(nèi)容

本場景演示如何通過 Fetch MCP 完成網(wǎng)頁內(nèi)容抓取。

1. 獲取 MCP SSE 的服務(wù)地址

進(jìn)入魔搭 MCP 市場，登錄后即可獲取 MCP SSE 的服務(wù)地址。
拷貝 SSE URL 字段。

2. MCP 服務(wù)添加

進(jìn)入個(gè)人設(shè)置中的 MCP 服務(wù)，然后在 MCP 服務(wù)頁面，完成 MCP 服務(wù)連接配置。

名稱： fetch
類型： SSE
服務(wù)地址： 粘貼您復(fù)制的 URL
例如：https://mcp-****.modelscope.cn/sse

3. 完成配置

添加成功后，當(dāng)圖標(biāo)顯示為連接成功。展開詳情，可以看到 MCP 提供的工具列表。

4. 在通義靈碼中使用 MCP

在通義靈碼的 IDE 的對話框左下角切換為智能體模式，并在對話框中輸入提示詞。

請輸入以下提示詞

幫我總結(jié)這篇文檔的內(nèi)容：https://help.aliyun.com/zh/lingma/developer-reference/listkbfiles-get-the-list-of-knowledge-base-files

請輸入以下提示詞

基于API文檔生成調(diào)用示例代碼：https://help.aliyun.com/zh/lingma/developer-reference/listkbfiles-get-the-list-of-knowledge-base-files

場景二：使用本地 MCP 查詢城市天氣

本場景演示如何通過 weather MCP 查詢城市天氣。

1. 前置環(huán)境檢查

確保您的本地環(huán)境已經(jīng)安裝 node.js，您可以讓通義靈碼完成前置環(huán)境檢查與準(zhǔn)備。

提示詞：

請幫我檢查我的本地環(huán)境，確保已經(jīng)安裝好node.js

2. MCP 服務(wù)添加

進(jìn)入個(gè)人設(shè)置中的 MCP 服務(wù)，然后在 MCP 服務(wù)頁面，完成 MCP 服務(wù)連接配置。

服務(wù)配置參數(shù)如下：

名稱：weather
類型：STDIO
命令：npx
參數(shù)：

-y @h1deya/mcp-server-weather

MCP 服務(wù)配置信息

服務(wù)配置信息

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

源碼地址：weather MCP 服務(wù)

3. 完成配置

添加成功后，當(dāng)圖標(biāo)顯示為連接成功。展開詳情，可以看到 MCP 提供的工具列表。

4. 在通義靈碼中使用 MCP

在通義靈碼的 IDE 對話框左下角切換為智能體模式，并在對話框中輸入提示詞。

提示詞1：

幫我查詢美國舊金山的天氣

提示詞2：

明天美國有天氣預(yù)警嗎？

MCP 使用常見問題

服務(wù)添加或安裝異常

1. 缺少 npx 命令所需環(huán)境

異常信息：failed to start command: exec: "npx": executable file not found in $PATH
解決方案： 下載并安裝 Node.js。

警告

Node.js 版本須在 v18 及以上，npm 版本須在 v8 及以上。版本過低可能導(dǎo)致工具調(diào)用失敗

您可以訪問 Node.js 官網(wǎng)，下載并安裝 Node.js 18 或更高版本，也可以選擇通過以下方式完成：

安裝驗(yàn)證步驟

1.下載并安裝

Windows 系統(tǒng)

使用 nvm-windows 管理多版本：

nvm install 22.14.0  # 安裝指定版本
nvm use 22.14.0

2.安裝完成后，在終端中運(yùn)行以下命令確認(rèn)是否安裝成功。

node -v
npx -v

3.安裝成功后，終端將顯示已安裝的 Node.js 版本號。

Mac 系統(tǒng)

使用 brew 安裝（需先安裝 brew）。

# 2. 驗(yàn)證核心工具鏈
brew update
brew install node

# 2. 驗(yàn)證核心工具鏈
echo "Node.js版本: $(node -v)"
echo "npm版本: $(npm -v)"
echo "npx版本: $(npx -v)"

# 3. 配置環(huán)境變量（必要時(shí)）
echo 'export PATH="/usr/local/opt/node@16/bin:$PATH"' >> ~/.zshrc

2.安裝完成后，在終端中運(yùn)行以下命令確認(rèn)是否安裝成功。

node -v
npx -v

3.安裝成功后，終端將顯示已安裝的 Node.js 版本號。

2. 缺少 uvx 命令所需環(huán)境

異常信息：failed to start command: exec: "uvx": executable file not found in $PATH
解決方案： 安裝 uvx （Python 3.8 及以上版本）。
- 您可以前往 Python 官網(wǎng)，下載并安裝 Python 3.8 或更高版本，也可以選擇通過以下方式完成：

安裝驗(yàn)證步驟

1.下載并安裝

Windows 系統(tǒng)

通過 Chocolatey 安裝（需先安裝Chocolatey）：

choco install uvx

2.安裝完成后，在終端中運(yùn)行以下命令確認(rèn)是否安裝成功。

uvx --version

3.安裝成功后，終端將顯示已安裝的 uvx 版本號。

Mac 系統(tǒng)

使用 brew 安裝（需先安裝 brew）。

# 1. 添加uvx官方倉庫
brew tap uvx/tools

# 2. 執(zhí)行一鍵安裝
brew install uvx

# 3. 驗(yàn)證安裝結(jié)果
uvx doctor --environment

# 4. 配置自動(dòng)更新（可選）
brew upgrade --cask uvx-updater

2.安裝完成后，在終端中運(yùn)行以下命令確認(rèn)是否安裝成功。

uvx --version

3.安裝成功后，終端將顯示已安裝的 uvx 版本號。

3. 無法初始化 MCP Client

異常信息：failed to initialize MCP client: context deadline exceeded
異常原因，包括但不限于以下原因：
- 服務(wù)參數(shù)配置錯(cuò)誤：MCP 服務(wù)的參數(shù)設(shè)置可能存在錯(cuò)誤或其他情況，影響服務(wù)初始化。
- 資源拉取失敗：由于網(wǎng)絡(luò)問題，無法成功拉取資源導(dǎo)致的安裝失敗。
- 網(wǎng)絡(luò)安全限制：由于公司內(nèi)部安全組件的攔截，導(dǎo)致 MCP 服務(wù)初始化異常。
排查步驟：

1.單擊復(fù)制完整命令，可以獲取完整的命令。

2.在終端中運(yùn)行該命令，可以獲取詳細(xì)異常信息。

3.分析異常信息，進(jìn)行對應(yīng)修復(fù)。

常見問題 1：配置錯(cuò)誤

在以上異常示例中，通過異常信息可以看出，是由于 Redis 連接URL 配置錯(cuò)誤導(dǎo)致連接失敗，據(jù)此應(yīng)檢查并通過編輯該MCP服務(wù)，修正錯(cuò)誤的URL配置。

常見問題2：資源拉取失敗

如果由于資源拉取問題導(dǎo)致命令運(yùn)行失敗，可以在命令行中執(zhí)行以下命令，添加鏡像源，再重啟 lingma 進(jìn)程后再試。

Windows 系統(tǒng)

npm config set registry https://registry.npmmirror.com

Mac 系統(tǒng)

export UV_INDEX_URL=https://mirrors.aliyun.com/pypi/simple/

常見問題3：Node.js 運(yùn)行被安全組件攔截

根據(jù)安全組件的攔截提示，對Node.js進(jìn)程或相關(guān)執(zhí)行文件進(jìn)行授權(quán)或加白操作。

工具使用相關(guān)問題

說明

如果您在使用 MCP 廣場中的服務(wù)存在問題，請聯(lián)系魔搭社區(qū)，獲取技術(shù)支持。

ModelScope 開發(fā)者群（釘釘群號 44837352）

1. 環(huán)境變量或參數(shù)填寫錯(cuò)誤，導(dǎo)致執(zhí)工具執(zhí)行失敗

排查步驟：

如果 MCP 工具調(diào)用出現(xiàn)異常或返回結(jié)果不符合預(yù)期，建議您首先展開工具調(diào)用詳情，查看具體的錯(cuò)誤信息，并據(jù)此進(jìn)行分析與排查。

重要

部分 MCP 服務(wù)（如 Mastergo 和 Figma）的 API_KEY 或 TOKEN 等關(guān)鍵認(rèn)證信息包含在“參數(shù)（args）”中。

因此，在通過 MCP 廣場安裝后，仍需手動(dòng)配置這些參數(shù)。

解決方案：

進(jìn)入我的服務(wù)頁面。
找到對應(yīng) MCP 服務(wù)，單擊編輯。
在服務(wù)配置中，查看參數(shù)（args） 部分。
替換其中需要更新或填寫的變量內(nèi)容，確保其準(zhǔn)確無誤，重新連接服務(wù)后再嘗試調(diào)用。

2. 模型無法正常調(diào)用 MCP 工具

確認(rèn)當(dāng)前在智能體模式。

重要

如果未打開相關(guān)工程目錄，系統(tǒng)將僅進(jìn)入智能問答模式，無法調(diào)用 MCP 工具。請先加載對應(yīng)的工程目錄，并切換到智能體模式。

確認(rèn) MCP 服務(wù)處于已連接狀態(tài)：

如果服務(wù)連接中斷，在界面右側(cè)單擊，系統(tǒng)會(huì)自動(dòng)嘗試重新啟動(dòng) MCP 服務(wù)。

使用建議： 建議避免MCP服務(wù)及其工具使用相似命名（如 TextAnalyzer-Pro 和 TextAnalyzer-Plus 都包含名為 fetchText 的工具且功能類似），防止模型調(diào)用時(shí)產(chǎn)生歧義。

3.個(gè)人設(shè)置、MCP 工具頁無法打開，會(huì)話面板顯示空白。

當(dāng)頁面顯示空白并在 idea.log 中有如下報(bào)錯(cuò)信息：“WARN - #c.i.u.j.JBCefApp - JCefAppConfig.class is not from a JBR module”。

異常原因： Android Studio 默認(rèn)設(shè)置不支持 JCEF，導(dǎo)致無法加載個(gè)人設(shè)置、MCP 等頁面。

解決方案：

配置 JCEF：在 IDE 中選擇****Help** > Find Action.. **，在彈出的輸入框中輸入 "Registry" 并打開。
- 啟用選項(xiàng)ide.browser.jcef.enabled
- 關(guān)閉選項(xiàng)ide.browser.jcef.sandbox.enable

配置 IDE Runtime：再次選擇****Help** > Find Action.. **，在輸入框中輸入 "Choose Boot Runtime for the IDE" 并打開，選擇較新的 JCEF Runtime 版本，然后確定。
重啟 IDE。

4. MCP 服務(wù)列表無法正常加載

服務(wù)列表持續(xù)顯示加載中。

重新啟動(dòng) IDE。
如果問題仍未解決，可嘗試手動(dòng)啟動(dòng) Lingma 服務(wù)：

Windows 系統(tǒng)

進(jìn)入目錄：.lingma/bin/x.x.x/CPU架構(gòu)_64_系統(tǒng)/

執(zhí)行命令：

Lingma.exe start

Mac 系統(tǒng)

單擊電腦左上角蘋果圖標(biāo)，選擇“關(guān)于本機(jī)”查看處理器型號，然后根據(jù)處理器型號進(jìn)入對應(yīng)的目錄。

m1 芯片：/.lingma/bin/x.x.x/aarch64_darwin/Lingma
intel 芯片：/.lingma/bin/x.x.x/x86_64_darwin/Lingma

執(zhí)行命令：

Lingma start

等待啟動(dòng)成功后，重新單擊登錄按鈕。

posted @ 2025-05-12 18:23 通義靈碼閱讀(2459) 評論(0) 收藏舉報(bào)

刷新頁面返回頂部

tongyilingma

如何在通義靈碼里使用 MCP 能力？

前提條件

模型上下文協(xié)議（Model Context Protocol）

MCP 服務(wù)配置與使用

添加 MCP 服務(wù)

1. 進(jìn)入 MCP 服務(wù)頁面

2. 添加服務(wù)

使用 MCP 工具

1. 輸入提示詞

2. 執(zhí)行工具

3. 查看工具執(zhí)行結(jié)果

4. 代碼審查與采納

場景使用示例

場景一：使用遠(yuǎn)端 MCP 抓取網(wǎng)頁內(nèi)容

1. 獲取 MCP SSE 的服務(wù)地址

2. MCP 服務(wù)添加

3. 完成配置

4. 在通義靈碼中使用 MCP

場景二：使用本地 MCP 查詢城市天氣

1. 前置環(huán)境檢查

2. MCP 服務(wù)添加

3. 完成配置

4. 在通義靈碼中使用 MCP

MCP 使用常見問題

服務(wù)添加或安裝異常

1. 缺少 npx 命令所需環(huán)境

安裝驗(yàn)證步驟

2. 缺少 uvx 命令所需環(huán)境

安裝驗(yàn)證步驟

3. 無法初始化 MCP Client

工具使用相關(guān)問題

1. 環(huán)境變量或參數(shù)填寫錯(cuò)誤，導(dǎo)致執(zhí)工具執(zhí)行失敗

2. 模型無法正常調(diào)用 MCP 工具

3.個(gè)人設(shè)置、MCP 工具頁無法打開，會(huì)話面板顯示空白。

4. MCP 服務(wù)列表無法正常加載

公告

tongyilingma

如何在通義靈碼里使用 MCP 能力？

前提條件

模型上下文協(xié)議（Model Context Protocol）

MCP 服務(wù)配置與使用

添加 MCP 服務(wù)

1. 進(jìn)入 MCP 服務(wù)頁面

2. 添加服務(wù)

使用 MCP 工具

1. 輸入提示詞

2. 執(zhí)行工具

3. 查看工具執(zhí)行結(jié)果

4. 代碼審查與采納

場景使用示例

場景一： 使用遠(yuǎn)端 MCP 抓取網(wǎng)頁內(nèi)容

1. 獲取 MCP SSE 的服務(wù)地址

2. MCP 服務(wù)添加

3. 完成配置

4. 在通義靈碼中使用 MCP

場景二： 使用本地 MCP 查詢城市天氣

1. 前置環(huán)境檢查

2. MCP 服務(wù)添加

3. 完成配置

4. 在通義靈碼中使用 MCP

MCP 使用常見問題

服務(wù)添加或安裝異常

1. 缺少 npx 命令所需環(huán)境

安裝驗(yàn)證步驟

2. 缺少 uvx 命令所需環(huán)境

安裝驗(yàn)證步驟

3. 無法初始化 MCP Client

工具使用相關(guān)問題

1. 環(huán)境變量或參數(shù)填寫錯(cuò)誤，導(dǎo)致執(zhí)工具執(zhí)行失敗

2. 模型無法正常調(diào)用 MCP 工具

3.個(gè)人設(shè)置、MCP 工具頁無法打開，會(huì)話面板顯示空白。

4. MCP 服務(wù)列表無法正常加載

公告

場景一：使用遠(yuǎn)端 MCP 抓取網(wǎng)頁內(nèi)容

場景二：使用本地 MCP 查詢城市天氣