AI 助理
备案控制台
官方文档
输入文档关键字查找
首页 表格存储 实践教程 AI实践 Tablestore MCP 服务快速入门

Tablestore MCP 服务快速入门

更新时间：
产品详情
我的收藏

表格存储（Tablestore）集成了MCP协议，通过向量和标量的混合检索能力，提供高效的数据存储与检索解决方案。通过本文您可以了解Tablestore MCP服务的使用方法。

功能介绍

Tablestore MCP服务提供了以下两个工具：

  • 存储工具（tablestore-store）：数据经过Embedding模型（默认为BAAI/bge-base-zh-v1.5）转成向量，连同原文本一起写入到表格存储。

  • 检索工具（tablestore-search）：用户的查询文本经过Embedding模型转成向量，检索表格存储的多元索引（使用向量和标量进行混合查询），召回用户期望的结果。

Tablestore 作为向量数据库有什么优势？

与传统数据库和专用向量数据库相比，Tablestore 在 MCP 的场景中有显著的优势：

  • 混合查询：原生支持向量和标量混合查询，其多元索引可以实现任意列的查询（主键列和非主键列）、多字段自由组合查询、地理位置查询、全文检索、模糊查询、嵌套查询、去重、排序、查询数据总行数和统计聚合等丰富的查询能力。

  • 快速落地与全周期支持：提供标准化的API接口/SQL查询，集成LangChain、LlamaIndex、PAI-RAG、LangEngine、LangChain4J、Dify、MCP等第三方开源框架，帮助用户提升开发效率，实现业务价值。

  • 产品生态：支持与阿里云大数据生态无缝对接，如RDS、Flink、MaxCompute等，避免数据孤岛。

  • Serverless：提供Serverless服务，免除软硬件的运维和扩容压力，您可以专注于业务创新和快速迭代。

  • 低成本：按需付费、存储计算分离，无需为闲置资源付费。

  • 弹性扩展：PB级的数据处理能力，支持自动水平分片与弹性资源调度。

准备工作

  • 开通表格存储服务并创建实例。

  • 为阿里云账号或具有表格存储访问权限的RAM用户创建AccessKey。

  • 准备一台部署 MCP Server 的服务器，您可以使用阿里云ECS。

    说明

    本文使用的 ECS 服务器操作系统为Alibaba Cloud Linux 3.2104 LTS 64位，Python版本为 3.13.2，Java 版本为 17.0.15。

使用步骤

步骤一：下载源码

  1. 安装Git。如果您使用的服务器已安装Git，请跳过该步骤。

    yum install git

  2. 下载源码。

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

    如果因为网络问题无法下载，您可以直接下载tablestore-mcp-server，将其上传到服务器后进行解压。解压命令如下：

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

步骤二：运行服务

表格存储提供Python和Java两个版本的MCP服务。

Python

Python版本的表格存储MCP服务需要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. 安装uv。

    pip3 install uv

    关于uv安装的详细信息请参见官方文档。

  3. 创建虚拟环境。如果您使用的是其它Python版本，请修改版本号。

    uv venv --python 3.13

  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

    表格存储实例的访问地址Endpoint。如果您使用的是ECS，请根据地域情况选择访问地址：

    • ECS与表格存储在同一地域：选择公网地址或者VPC地址。

    • ECS与表格存储不在同一地域：选择公网地址。

    重要

    表格存储新创建的实例默认不开启公网访问，如果您需要使用公网访问地址，请在表格存储控制台实例管理的网络管理页签中允许网络类型选中公网，并单击设置保存配置。

    TABLESTORE_INSTANCE_NAME

    表格存储实例的名称。

    其它可选的环境变量

    变量名称

    说明

    SERVER_PORT

    服务运行的端口，默认值为8001。

    TABLESTORE_TABLE_NAME

    表格存储的数据表名称，默认值为ts_mcp_server_py_v1。

    TABLESTORE_INDEX_NAME

    表格存储数据表的多元索引名称，默认值为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

运行表格存储MCP服务需要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

    表格存储实例的访问地址Endpoint。如果您使用的是ECS，请根据地域情况选择访问地址：

    • ECS与表格存储在同一地域：选择公网地址或者VPC地址。

    • ECS与表格存储不在同一地域：选择公网地址。

    重要

    表格存储新创建的实例默认不开启公网访问，如果您需要使用公网访问地址，请在表格存储控制台实例管理的网络管理页签中允许网络类型选中公网，并单击设置保存配置。

    TABLESTORE_INSTANCE_NAME

    表格存储实例的名称。

    其它可选的环境变量

    变量名称

    说明

    SERVER_PORT

    服务运行的端口，默认值为8080。

    TABLESTORE_TABLE_NAME

    表格存储的数据表名称，默认值为tablestore_java_mcp_server_v1。

    TABLESTORE_INDEX_NAME

    表格存储数据表的多元索引名称，默认值为tablestore_java_mcp_server_index_v1。

    TABLESTORE_TABLE_PK_NAME

    表格存储数据表的主键名称，默认值为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. 默认模型：设置默认模型，您也可以在对话页面选择模型。

      image

    3. MCP服务器：单击添加服务器，名称和描述可以自定义，类型选择SSE，URL的格式为 http://server_ip:port/sse，Python默认的端口为8001，Java默认的端口为8080。首次进入MCP服务器设置页面还需要按照提示安装UV和Bun。

      重要

      如果您使用的是ECS，需要添加安全组规则，在入方向规则中添加自定义TCP端口的允许访问策略，访问目的端口为MCP服务运行的端口。

      image

  3. 在对话页面选择MCP服务器。

    image

  4. 与助手进行对话，将文档写入到表格存储中。

    image

    您可以在服务器中查看MCP调用日志。

    INFO:mcp.server.lowlevel.server:Processing request of type CallToolRequest
Batches: 100%|█████████████████████████████████████████████████████████████████████████████████████████████████| 1/1 [00:00<00:00,  8.01it/s]
INFO:tablestore_mcp_server.tablestore_connector:Storing Node ID: 95186b3b-1aae-4f99-ae5e-da884121943c
Text: 阿里云 ECS 提供了两种基础计费方式：按量付费和包年包月。按量付费是根据实际使用时长进行计费，适合短期或临时需求；包年包月则是
预付费模式，用户可以按照一年或一个月的周期购买 ECS 实例，适用于长期稳定的需求。

    您也可以在表格存储控制台查看写入的数据。

    image

  5. 与助手进行会话，检索表格存储中的相关文档。

    image

    您可以在服务器中查看MCP调用日志。

    INFO:mcp.server.lowlevel.server:Processing request of type CallToolRequest
INFO:tablestore_mcp_server.tablestore_connector:Search query: ECS 计费文档, size: 5
Batches: 100%|█████████████████████████████████████████████████████████████████████████████████████████████████| 1/1 [00:00<00:00, 14.01it/s]
INFO:llama_index.vector_stores.tablestore.base:Tablestore search successfully. request_id:000639da-7c05-7de9-a78c-390a0d2f3fdd

本地调试和二次开发

您可以在本地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，查看可调试的工具。

    image

  4. 选择tablestore-store工具，在information中输入内容，单击Run Tool，向表格存储中写入数据。

    image

    您可以在IDE控制台查看日志，或者登录表格存储控制台查看数据。

    image

  5. 选择tablestore-search工具，在query中输入查询内容和size（返回的数据条目），单击Run Tool，查询表格存储中的数据。

    image

升级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

相关文档

上一篇：AI实践下一篇：跨应用的AI记忆：Tablestore OpenMemory MCP