全部產品
Search

搜尋本產品

    Tablestore：Tablestore MCP Server

    文件中心

    Tablestore：Tablestore MCP Server

    更新時間：Jun 04, 2026

    Table Store（Tablestore）整合了MCP協議，通過向量和標量的混合檢索能力，提供高效的資料存放區與檢索解決方案。以下介紹Tablestore MCP服務的使用方法。

    功能介紹

    Tablestore MCP服務提供了以下兩個工具：

    • 儲存工具（tablestore-store）：資料經過Embedding模型（預設為BAAI/bge-base-zh-v1.5）轉換為向量，連同原文本一起寫入Table Store。

    • 檢索工具（tablestore-search）：查詢文本經過Embedding模型轉換為向量，檢索Table Store的多元索引（使用向量和標量進行混合查詢），召回期望的結果。

    Tablestore 作為向量資料庫有什麼優勢？

    與傳統資料庫和專用向量資料庫相比，Tablestore 在 MCP 的情境中有顯著的優勢：

    • 混合查詢：原生支援向量和標量混合查詢，多元索引實現任意列查詢（主鍵列和非主鍵列）、多欄位自由組合查詢、地理位置查詢、全文檢索索引、模糊查詢、巢狀查詢、去重、排序、查詢資料總行數和統計彙總等豐富功能，滿足複雜業務情境需求。

    • 快速落地與全周期支援：提供標準化API介面和SQL查詢，整合LangChain、LlamaIndex、PAI-RAG、LangEngine、LangChain4J、Dify、MCP等主流開源架構，顯著提升開發效率和業務價值實現速度。

    • 產品生態：與阿里雲巨量資料生態無縫對接，支援RDS、Flink、MaxCompute等服務，避免資料孤島問題。

    • Serverless：提供Serverless服務，免除軟硬體營運和擴容壓力，專註於業務創新和快速迭代。

    • 低成本：按需付費、儲存計算分離架構，無需為閑置資源付費。

    • 彈性擴充：PB級資料處理能力，支援自動水平分區與彈性資源調度。

    準備工作

    使用步驟

    步驟一：下載源碼

    1. 安裝Git。如果伺服器已安裝Git，請跳過該步驟。

      yum -y install git

    2. 下載源碼。

      git clone https://github.com/aliyun/alibabacloud-tablestore-mcp-server

      如果因網路問題無法下載，可直接下載tablestore-mcp-server，上傳到伺服器後進行解壓。解壓命令如下：

      tar -zxvf alibabacloud-tablestore-mcp-server.tar.gz

    步驟二：運行服務

    Table Store提供Python和Java兩個版本的MCP服務。

    Python

    Python版本的Table StoreMCP服務需要Python3.10及以上版本，並使用uv進行包和環境管理。

    Alibaba Cloud Linux 3.2104 LTS 64位系統預設的Python3版本為3.6.8，升級 Python 版本操作請參見升級 Python 版本。

    1. 進入MCP的源碼目錄。

      cd alibabacloud-tablestore-mcp-server/tablestore-python-mcp-server

    2. 建立虛擬環境並啟用。

      python3 -m venv .venv && source .venv/bin/activate

    3. 安裝uv。

      pip3 install uv

    4. 配置環境變數。

      export HF_ENDPOINT=https://huggingface.co
export TABLESTORE_ACCESS_KEY_ID=LTAI********************
export TABLESTORE_ACCESS_KEY_SECRET=******************************
export TABLESTORE_ENDPOINT=https://k01r********.cn-hangzhou.ots.aliyuncs.com
export TABLESTORE_INSTANCE_NAME=k01r********

      環境變數說明如下。

      變數名稱

      說明

      HF_ENDPOINT

      HuggingFace地址。

      TABLESTORE_ACCESS_KEY_ID

      阿里雲帳號或RAM使用者的AccessKey ID。

      TABLESTORE_ACCESS_KEY_SECRET

      阿里雲帳號或RAM使用者的AccessKey Secret。

      TABLESTORE_ENDPOINT

      Table Store執行個體的訪問地址Endpoint。如果使用ECS，請根據地區情況選擇訪問地址：

      • ECS與Table Store在同一地區：選擇公網地址或者VPC地址。

      • ECS與Table Store不在同一地區：選擇公網地址。

      重要

      Table Store新建立的執行個體預設不開啟公網訪問，如需使用公網訪問地址，請在Table Store控制台執行個體管理的網絡管理頁簽中允許網路類型選中公網，並單擊設置儲存配置。

      TABLESTORE_INSTANCE_NAME

      Table Store執行個體的名稱。

      其它可選的環境變數

      變數名稱

      說明

      SERVER_PORT

      服務啟動並執行連接埠，預設值為8001。

      TABLESTORE_TABLE_NAME

      Table Store的資料表名稱，預設值為ts_mcp_server_py_v1。

      TABLESTORE_INDEX_NAME

      Table Store資料表的多元索引名稱，預設值為ts_mcp_server_py_index_v1。

      TABLESTORE_VECTOR_DIMENSION

      向量維度，預設為768。向量維度需要與Embedding模型的向量維度保持一致。

      TABLESTORE_TEXT_FIELD

      文字欄位名稱，預設值為_content。

      TABLESTORE_VECTOR_FIELD

      向量欄位名稱，預設值為_embedding。

      EMBEDDING_PROVIDER_TYPE

      Embedding模型提供者，目前只支援hugging_face。

      EMBEDDING_MODEL_NAME

      Embedding模型名稱，預設值為BAAI/bge-base-zh-v1.5。Embedding模型的向量維度需要與TABLESTORE_VECTOR_DIMENSION保持一致。

      TOOL_STORE_DESCRIPTION

      寫入工具的描述資訊。

      TOOL_SEARCH_DESCRIPTION

      檢索工具的描述資訊。

    5. 運行MCP服務。

      uv run tablestore-mcp-server

      初次運行需要下載依賴，請耐心等待。如因網路問題導致下載中斷，重新執行命令即可。運行成功後，會列印如下日誌：

      INFO:tablestore_mcp_server.server:mcp host:0.0.0.0, port:8001
INFO:root:run tablestore-mcp-server by: sse

    Java

    運行Table StoreMCP服務需要JDK17版本。

    1. 安裝JDK。

      yum -y install java-17-openjdk-devel.x86_64

    2. 進入MCP的源碼目錄。

      cd alibabacloud-tablestore-mcp-server/tablestore-java-mcp-server

    3. 編譯源碼。

      ./mvnw package -DskipTests -s settings.xml

      編譯成功後，會列印如下日誌。

      [INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  01:58 min
[INFO] Finished at: 2025-03-26T11:31:21+08:00
[INFO] ------------------------------------------------------------------------

    4. 配置環境變數。

      export HF_ENDPOINT=http://hf-mirror.com
export TABLESTORE_ACCESS_KEY_ID=LTAI********************
export TABLESTORE_ACCESS_KEY_SECRET=******************************
export TABLESTORE_ENDPOINT=https://k01r********.cn-hangzhou.ots.aliyuncs.com
export TABLESTORE_INSTANCE_NAME=k01r********

      環境變數說明如下。

      變數名稱

      說明

      HF_ENDPOINT

      HuggingFace鏡像地址。

      TABLESTORE_ACCESS_KEY_ID

      阿里雲帳號或RAM使用者的AccessKey ID。

      TABLESTORE_ACCESS_KEY_SECRET

      阿里雲帳號或RAM使用者的AccessKey Secret。

      TABLESTORE_ENDPOINT

      Table Store執行個體的訪問地址Endpoint。如果使用ECS，請根據地區情況選擇訪問地址：

      • ECS與Table Store在同一地區：選擇公網地址或者VPC地址。

      • ECS與Table Store不在同一地區：選擇公網地址。

      重要

      Table Store新建立的執行個體預設不開啟公網訪問，如需使用公網訪問地址，請在Table Store控制台執行個體管理的網絡管理頁簽中允許網路類型選中公網，並單擊設置儲存配置。

      TABLESTORE_INSTANCE_NAME

      Table Store執行個體的名稱。

      其它可選的環境變數

      變數名稱

      說明

      SERVER_PORT

      服務啟動並執行連接埠，預設值為8080。

      TABLESTORE_TABLE_NAME

      Table Store的資料表名稱，預設值為tablestore_java_mcp_server_v1。

      TABLESTORE_INDEX_NAME

      Table Store資料表的多元索引名稱，預設值為tablestore_java_mcp_server_index_v1。

      TABLESTORE_TABLE_PK_NAME

      Table Store資料表的主鍵名稱，預設值為id。

      TABLESTORE_VECTOR_DIMENSION

      向量維度。預設為768。向量維度需要與Embedding模型的向量維度保持一致。

      TABLESTORE_TEXT_FIELD

      文字欄位名稱，預設值為_content。

      TABLESTORE_VECTOR_FIELD

      向量欄位名稱，預設值為_embedding。

      EMBEDDING_MODEL_NAME

      Embedding模型名稱，預設值為ai.djl.huggingface.rust/BAAI/bge-base-en-v1.5/0.0.1/bge-base-en-v1.5。Embedding模型的向量維度需要與TABLESTORE_VECTOR_DIMENSION保持一致。

    5. 運行MCP服務。

      java -jar target/tablestore-java-mcp-server-1.0-SNAPSHOT.jar

      運行成功後，會列印如下日誌。

      2025-03-26T11:35:31.519+08:00  INFO 5116 --- [           main] o.s.b.web.embedded.netty.NettyWebServer  : Netty started on port 8080 (http)
2025-03-26T11:35:31.534+08:00  INFO 5116 --- [           main] c.a.openservices.tablestore.sample.App   : Started App in 44.143 seconds (process running for 44.766)

    步驟三：使用MCP服務

    1. 前往Cherry Studio官網下載並安裝用戶端。

    2. 單擊左下角的設定按鈕，設定模型服務、預設模型和MCP伺服器。

      1. 模型服務：Cherry Studio內建了多種模型服務商，根據需要選擇模型服務商，擷取服務商的API密鑰並在模型服務中填寫密鑰以及管理模型。樣本使用阿里雲百鍊的qwen-max模型，使用前需要擷取API Key。

      2. 預設模型：設定預設模型，也可在對話頁面選擇模型。

        在訊息輸入區工具列中單擊 @ 表徵圖開啟模型選擇面板，可選擇 qwen-vl-plus、qwen-coder-plus、qwen-turbo、qwen-plus、qwen-max 等阿里雲百鍊模型。

      3. MCP伺服器：單擊添加伺服器，名稱和描述可以自訂，類型選擇SSE，URL的格式為 http://server_ip:port/sse，Python預設的連接埠為8001，Java預設的連接埠為8080。首次進入MCP伺服器設定頁面還需要按照提示安裝UV和Bun。

        重要

        如果使用ECS，需要添加安全性群組規則，在入方向規則中添加自訂TCP連接埠的允許存取原則，訪問目的連接埠為MCP服務啟動並執行連接埠。

        在要求標頭地區配置 Content-Type=application/json 和 Authorization=Bearer token。

    3. 在對話頁面選擇MCP伺服器。

      底部工具列中綠色終端表徵圖即為該入口，單擊後彈出面板顯示Table Store（Tablestore）已成功串連，串連地址格式為 http://<IP地址>:8001/sse，綠色對勾表示串連正常。

    4. 與助手進行對話，將文檔寫入到Table Store中。

      在對話方塊中輸入問題，例如阿里雲 ECS 有幾種基礎計費方式，幫我產生一個文檔，寫入到Table Store（Tablestore）中。助手回複中會顯示 tablestore-store 工具調用卡片，狀態為已完成 ✓，表示文檔已成功通過 MCP 工具寫入Table Store。

      可在伺服器中查看MCP調用日誌：

      INFO:mcp.server.lowlevel.server:Processing request of type CallToolRequest
Batches: 100%|█████████████████████████████████████████████████████████████████████████████████████████████████| 1/1 [00:00<00:00, 13.82it/s]
INFO:tablestore_mcp_server.tablestore_connector:Storing Node ID: 2d80f2ab-9996-49d4-b23f-28b3d02b70bc
Text: There are two base billing models for Alibaba Cloud ECS: Pay-As-
You-Go and Subscription.

      也可在Table Store控制台查看寫入的資料。

      表 ts_mcp_server_py_v1 的資料管理頁簽中顯示已寫入的資料行，包含 id（主鍵）、_content、_embedding、title 列，可確認資料已成功儲存。

    5. 與助手進行會話，檢索Table Store中的相關文檔。

      在助手的回複中，頂部會顯示 tablestore-search 工具調用狀態為"已完成 ✓"，表示 MCP 服務已成功檢索Table Store中的相關文檔，並基於檢索結果產生回答。

      可在伺服器中查看MCP調用日誌：

      INFO:mcp.server.lowlevel.server:Processing request of type CallToolRequest
INFO:tablestore_mcp_server.tablestore_connector:Search query: Alibaba Cloud ECS billing models, size: 5
Batches: 100%|█████████████████████████████████████████████████████████████████████████████████████████████████| 1/1 [00:00<00:00, 14.34it/s]
INFO:llama_index.vector_stores.tablestore.base:Tablestore search successfully. request_id:000639da-cc10-5075-8fac-bb0a59c4b4bd

    本地調試和二次開發

    可在本地IDE運行MCP源碼，並使用MCP Inspector工具進行調試。

    步驟一：配置環境變數

    運行代碼前，需要先配置系統內容變數，配置完成後請重啟或重新整理編譯運行環境，包括IDE、命令列介面、其它傳統型應用程式及後台服務，確保最新的系統內容變數成功載入。

    Linux

    1. 在命令列介面執行以下命令來將環境變數設定追加到 ~/.bashrc 檔案中。

      echo "export TABLESTORE_ACCESS_KEY_ID='LTAI********************'" >> ~/.bashrc
echo "export TABLESTORE_ACCESS_KEY_SECRET='******************************'" >> ~/.bashrc
echo "export TABLESTORE_ENDPOINT='https://k01r********.cn-hangzhou.ots.aliyuncs.com'" >> ~/.bashrc
echo "export TABLESTORE_INSTANCE_NAME='k01r********'" >> ~/.bashrc
echo "export HF_ENDPOINT='http://hf-mirror.com'" >> ~/.bashrc

    2. 執行以下命令使變更生效。

      source ~/.bashrc

    3. 執行以下命令檢查環境變數是否生效。

      echo $TABLESTORE_ACCESS_KEY_ID
echo $TABLESTORE_ACCESS_KEY_SECRET
echo $TABLESTORE_ENDPOINT
echo $TABLESTORE_INSTANCE_NAME
echo $HF_ENDPOINT

    macOS

    1. 在終端中執行以下命令，查看預設 Shell 類型。

      echo $SHELL

    2. 根據預設 Shell 類型進行操作。

      Zsh

      1. 執行以下命令來將環境變數設定追加到 ~/.zshrc 檔案中。

        echo "export TABLESTORE_ACCESS_KEY_ID='LTAI********************'" >> ~/.zshrc
echo "export TABLESTORE_ACCESS_KEY_SECRET='******************************'" >> ~/.zshrc
echo "export TABLESTORE_ENDPOINT='https://k01r********.cn-hangzhou.ots.aliyuncs.com'" >> ~/.zshrc
echo "export TABLESTORE_INSTANCE_NAME='k01r********'" >> ~/.zshrc
echo "export HF_ENDPOINT='http://hf-mirror.com'" >> ~/.zshrc

      2. 執行以下命令使變更生效。

        source ~/.zshrc

      3. 執行以下命令檢查環境變數是否生效。

        echo $TABLESTORE_ACCESS_KEY_ID
echo $TABLESTORE_ACCESS_KEY_SECRET
echo $TABLESTORE_ENDPOINT
echo $TABLESTORE_INSTANCE_NAME
echo $HF_ENDPOINT

      Bash

      1. 執行以下命令來將環境變數設定追加到 ~/.bash_profile 檔案中。

        echo "export TABLESTORE_ACCESS_KEY_ID='LTAI********************'" >> ~/.bash_profile
echo "export TABLESTORE_ACCESS_KEY_SECRET='******************************'" >> ~/.bash_profile
echo "export TABLESTORE_ENDPOINT='https://k01r********.cn-hangzhou.ots.aliyuncs.com'" >> ~/.bash_profile
echo "export TABLESTORE_INSTANCE_NAME='k01r********'" >> ~/.bash_profile
echo "export HF_ENDPOINT='http://hf-mirror.com'" >> ~/.bash_profile

      2. 執行以下命令使變更生效。

        source ~/.bash_profile

      3. 執行以下命令檢查環境變數是否生效。

        echo $TABLESTORE_ACCESS_KEY_ID
echo $TABLESTORE_ACCESS_KEY_SECRET
echo $TABLESTORE_ENDPOINT
echo $TABLESTORE_INSTANCE_NAME
echo $HF_ENDPOINT

    Windows

    CMD

    1. 在CMD中運行以下命令設定環境變數。

      setx TABLESTORE_ACCESS_KEY_ID "LTAI********************"
setx TABLESTORE_ACCESS_KEY_SECRET "******************************"
setx TABLESTORE_ENDPOINT "https://k01r********.cn-hangzhou.ots.aliyuncs.com"
setx TABLESTORE_INSTANCE_NAME "k01r********"
setx HF_ENDPOINT "http://hf-mirror.com"

    2. 重啟CMD後，運行以下命令檢查環境變數是否生效。

      echo %TABLESTORE_ACCESS_KEY_ID%
echo %TABLESTORE_ACCESS_KEY_SECRET%
echo %TABLESTORE_ENDPOINT%
echo %TABLESTORE_INSTANCE_NAME%
echo %HF_ENDPOINT%

    PowerShell

    1. 在PowerShell中運行以下命令。

      [Environment]::SetEnvironmentVariable("TABLESTORE_ACCESS_KEY_ID", "LTAI********************", [EnvironmentVariableTarget]::User)
[Environment]::SetEnvironmentVariable("TABLESTORE_ACCESS_KEY_SECRET", "******************************", [EnvironmentVariableTarget]::User)
[Environment]::SetEnvironmentVariable("TABLESTORE_ENDPOINT", "https://k01r********.cn-hangzhou.ots.aliyuncs.com", [EnvironmentVariableTarget]::User)
[Environment]::SetEnvironmentVariable("TABLESTORE_INSTANCE_NAME", "k01r********", [EnvironmentVariableTarget]::User)
[Environment]::SetEnvironmentVariable("HF_ENDPOINT", "http://hf-mirror.com", [EnvironmentVariableTarget]::User)

    2. 運行以下命令，檢查環境變數是否生效。

      [Environment]::GetEnvironmentVariable("TABLESTORE_ACCESS_KEY_ID", [EnvironmentVariableTarget]::User)
[Environment]::GetEnvironmentVariable("TABLESTORE_ACCESS_KEY_SECRET", [EnvironmentVariableTarget]::User)
[Environment]::GetEnvironmentVariable("TABLESTORE_ENDPOINT", [EnvironmentVariableTarget]::User)
[Environment]::GetEnvironmentVariable("TABLESTORE_INSTANCE_NAME", [EnvironmentVariableTarget]::User)
[Environment]::GetEnvironmentVariable("HF_ENDPOINT", [EnvironmentVariableTarget]::User)

    步驟二：運行源碼

    Python

    本地運行MCP源碼的環境要求：

    • Python 3.10及以上版本。

    • PyCharm 2024.3.2及以上版本。

    • 在PyCharm中配置uv環境。

    完成環境配置後，需要在PyCharm中開啟MCP的源碼目錄 tablestore-python-mcp-server，並運行 src/tablestore_mcp_server/main.py 檔案。運行成功後，控制台會列印如下日誌。

    INFO:tablestore_mcp_server.server:mcp host:0.0.0.0, port:8001
INFO:root:run tablestore-mcp-server by: sse

    Java

    本地運行MCP源碼的環境要求：JDK17。

    完成環境配置後，需要在IDEA中開啟MCP的源碼目錄 tablestore-java-mcp-server，並運行 src/main/java/com.alicloud.openservices.tablestore.sample/App.java 檔案。運行成功後，控制台會列印如下日誌。

    2025-03-31T16:50:50.582+08:00  INFO 27160 --- [           main] o.s.b.web.embedded.netty.NettyWebServer  : Netty started on port 8080 (http)
2025-03-31T16:50:50.594+08:00  INFO 27160 --- [           main] c.a.openservices.tablestore.sample.App   : Started App in 79.764 seconds (process running for 80.524)

    步驟三：工具調試

    1. 安裝Node.js。

    2. 在終端工具中執行以下命令，根據提示輸入 y，運行MCP Inspector。

      npx @modelcontextprotocol/inspector node build/index.js

      初次運行需要下載工具，請等待一段時間。運行成功後，終端會列印以下內容，連接埠以實際運行情況為準。

      MCP Inspector is up and running at:
   http://localhost:6274

    3. 在瀏覽器中訪問終端輸出的訪問地址，進入MCP Inspector管理頁面。根據本地運行情況選擇傳輸類型並填寫URL，單擊Connect串連MCP服務。可單擊List Tools查看可調試的工具。

      例如，Transport Type 選擇 SSE，URL 填寫 http://localhost:8001/sse，串連成功後狀態顯示為綠色 Connected。單擊 List Tools 後可看到登入的工具：tablestore-store（將文檔儲存到 Tablestore 以供後續檢索）和 tablestore-search（從 Tablestore 中使用自然語言搜尋相似性文檔）。

    4. 選擇tablestore-store工具，在information中輸入內容，單擊Run Tool，向Table Store中寫入資料。

      可在IDE控制台查看日誌，或者登入Table Store控制台查看資料。

      在Table Store控制台的資料管理 Tab 中，可看到表 ts_mcp_server_py_v1 已成功寫入一條資料，包含 id（主鍵）、_content（常值內容）和 _embedding（向量）三列，確認資料寫入成功。

    5. 選擇tablestore-search工具，在query中輸入查詢內容和size（返回的資料條目），單擊Run Tool，查詢Table Store中的資料。

      運行成功後，返回結果中會顯示與查詢內容語義相似的文檔條目，包含匹配文檔的常值內容（_content）及相似性分數（_score）等資訊。

    升級Python版本

    以下以Python3.13.2為例介紹如何升級Python版本。

    1. 下載Python。

      wget https://www.python.org/ftp/python/3.13.2/Python-3.13.2.tgz

      如果因為網路問題無法下載，可直接下載Python-3.13.2，並將其上傳到伺服器。

    2. 解壓檔案。

      tar -zxvf Python-3.13.2.tgz

    3. 安裝依賴。

      yum -y install zlib-devel bzip2-devel openssl-devel ncurses-devel sqlite-devel readline-devel tk-devel gdbm-devel xz-devel libffi-devel libuuid-devel libtirpc-devel libnsl2-devel

    4. 進入Python目錄。

      cd Python-3.13.2

    5. 配置安裝路徑。

      ./configure

    6. 編譯Python。

      make

    7. 安裝Python。

      make install

    8. 查看已安裝的版本。

      1. 查看Python版本。

        python3 --version

      2. 查看Pip版本。

        pip3 --version

    相關文檔