Deploy Tablestore MCP Server for AI Retrieval - Tablestore

Tablestore integrates the MCP protocol to offer efficient data storage and retrieval through hybrid vector and scalar capabilities. This topic explains how to use the Tablestore MCP service.

Background

Tablestore MCP service provides the following two tools:

Storage tool (tablestore-store): Data is converted into vectors through an embedding model (default is BAAI/bge-base-zh-v1.5) and written into Tablestore along with the original text.
Retrieval tool (tablestore-search): The user's query text is converted into vectors through an embedding model, and the search index of Tablestore is searched (using vectors and scalars for hybrid queries) to retrieve the results expected by the user.

What are the advantages of Tablestore as a vector database?

Compared with traditional databases and dedicated vector databases, Tablestore has significant advantages in MCP scenarios:

Hybrid queries: Native support for hybrid queries of vectors and scalars. Its search index can implement queries on any column (primary key columns and non-primary key columns), multi-field free combination queries, geolocation queries, full-text index, fuzzy queries, nested queries, deduplication, sorting, query of total number of rows, and statistical aggregation.
Rapid deployment and full lifecycle support: Provides standardized API operations/SQL queries, integrates with third-party open-source frameworks such as LangChain, LlamaIndex, PAI-RAG, LangEngine, LangChain4J, Dify, and MCP to help users improve development efficiency and achieve business value.
Product ecosystem: Supports seamless integration with Alibaba Cloud big data ecosystem, such as ApsaraDB RDS, Flink, MaxCompute, etc., avoiding data silos.
Serverless: Provides Serverless services, eliminating the pressure of hardware and software maintenance and expansion, allowing you to focus on business innovation and rapid iteration.
Low cost: Pay-as-you-go, separation of storage and computation, no need to pay for idle resources.
Elastic scaling: PB-level data processing capability, supporting automatic horizontal sharding and elastic resource scheduling.

Preparations

Activate a service and create an instance.
Create an AccessKey for your Alibaba Cloud account or a Resource Access Management (RAM) user with access permissions to Tablestore.
Prepare a server to deploy the MCP server. You can use Alibaba Cloud ECS.
Note
This topic uses an ECS server with Alibaba Cloud Linux 3.2104 LTS 64-bit operating system, Python 3.13.2, and Java 17.0.15.

Procedure

Step 1: Download the source code

Install Git. Skip this step if Git is already installed on your server.
```
yum -y install git
```
Download the source code.
```
git clone https://github.com/aliyun/alibabacloud-tablestore-mcp-server
```
If you cannot download due to network issues, directly download tablestore-mcp-server, upload it to your server, and decompress it. Run the following command to decompress:
```
tar -zxvf alibabacloud-tablestore-mcp-server.tar.gz
```

Step 2: Run the service

Tablestore provides both Python and Java versions of the MCP service.

Python

The Python version of the Tablestore MCP service requires Python 3.10 or later, and uses uv for package and environment management.

The default Python 3 version in Alibaba Cloud Linux 3.2104 LTS 64-bit system is 3.6.8. For instructions on upgrading Python, see Upgrade Python version.

Navigate to the MCP source code directory.

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

Create and activate a virtual environment.

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

Install uv.
```
pip3 install uv
```

Configure the environment variables.

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********

The environment variables are described as follows.

Variable name	Description
HF_ENDPOINT	HuggingFace address.
TABLESTORE_ACCESS_KEY_ID	The AccessKey ID of your Alibaba Cloud account or RAM user.
TABLESTORE_ACCESS_KEY_SECRET	The AccessKey secret of your Alibaba Cloud account or RAM user.
TABLESTORE_ENDPOINT	The endpoint of the Tablestore instance. If you are using ECS, select the endpoint based on the region: If ECS and Tablestore are in the same region: Select the public endpoint or VPC endpoint. If ECS and Tablestore are not in the same region: Select the public endpoint. Important Newly created Tablestore instances do not have public access enabled by default. To use a public endpoint, go to the Tablestore console, enter the Network Management tab of the Instance Management page, select Internet for Allowed Network Type, and click Settings to save the configuration.
TABLESTORE_INSTANCE_NAME	The name of the Tablestore instance.

Other optional environment variables

Variable name	Description
SERVER_PORT	The port on which the service runs. The default value is 8001.
TABLESTORE_TABLE_NAME	The name of the Tablestore data table. The default value is ts_mcp_server_py_v1.
TABLESTORE_INDEX_NAME	The name of the search index for the Tablestore data table. The default value is ts_mcp_server_py_index_v1.
TABLESTORE_VECTOR_DIMENSION	The number of dimensions. The default value is 768. The number of dimensions must be consistent with the vector dimension of the embedding model.
TABLESTORE_TEXT_FIELD	The name of the text field. The default value is _content.
TABLESTORE_VECTOR_FIELD	The name of the vector field. The default value is _embedding.
EMBEDDING_PROVIDER_TYPE	The embedding model provider. Currently, only hugging_face is supported.
EMBEDDING_MODEL_NAME	The name of the embedding model. The default value is BAAI/bge-base-zh-v1.5. The vector dimension of the embedding model must be consistent with TABLESTORE_VECTOR_DIMENSION.
TOOL_STORE_DESCRIPTION	The description of the storage tool.
TOOL_SEARCH_DESCRIPTION	The description of the retrieval tool.

Run the MCP service.
```
uv run tablestore-mcp-server
```
The first run requires downloading dependencies. Please be patient. If the download is interrupted due to network issues, simply run the command again. When the service runs successfully, the following logs will be printed.
```
INFO:tablestore_mcp_server.server:mcp host:0.0.0.0, port:8001
INFO:root:run tablestore-mcp-server by: sse
```

Java

Running the Tablestore MCP service requires JDK17.

Install JDK.

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

Navigate to the MCP source code directory.

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

Compile the source code.

./mvnw package -DskipTests -s settings.xml

When the compilation is successful, the following logs will be printed.

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

Configure the environment variables.

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********

The environment variables are described as follows.

Variable name	Description
HF_ENDPOINT	HuggingFace mirror address.
TABLESTORE_ACCESS_KEY_ID	The AccessKey ID of your Alibaba Cloud account or RAM user.
TABLESTORE_ACCESS_KEY_SECRET	The AccessKey secret of your Alibaba Cloud account or RAM user.
TABLESTORE_ENDPOINT	The endpoint of the Tablestore instance. If you are using ECS, select the endpoint based on the region: If ECS and Tablestore are in the same region: Select the public endpoint or VPC endpoint. If ECS and Tablestore are not in the same region: Select the public endpoint. Important Newly created Tablestore instances do not have public access enabled by default. To use a public endpoint, go to the Tablestore console, select Instance Management, go to the Network Management tab, select Allowed Network Types, check Public, and click Set to save the configuration.
TABLESTORE_INSTANCE_NAME	The name of the Tablestore instance.

Other optional environment variables

Variable name	Description
SERVER_PORT	The port on which the service runs. The default value is 8080.
TABLESTORE_TABLE_NAME	The name of the Tablestore data table. The default value is tablestore_java_mcp_server_v1.
TABLESTORE_INDEX_NAME	The name of the search index for the Tablestore data table. The default value is tablestore_java_mcp_server_index_v1.
TABLESTORE_TABLE_PK_NAME	The name of the primary key for the Tablestore data table. The default value is id.
TABLESTORE_VECTOR_DIMENSION	The number of dimensions. The default value is 768. The number of dimensions must be consistent with the vector dimension of the embedding model.
TABLESTORE_TEXT_FIELD	The name of the text field. The default value is _content.
TABLESTORE_VECTOR_FIELD	The name of the vector field. The default value is _embedding.
EMBEDDING_MODEL_NAME	The name of the embedding model. The default value is ai.djl.huggingface.rust/BAAI/bge-base-en-v1.5/0.0.1/bge-base-en-v1.5. The vector dimension of the embedding model must be consistent with TABLESTORE_VECTOR_DIMENSION.

Run the MCP service.

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

When the service runs successfully, the following logs will be printed.

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)

Step 3: Use the MCP service

Go to the Cherry Studio website to download and install the client.
Click the settings button in the lower left corner to configure the model service, default model, and MCP server.
1. Model Service: Cherry Studio has many built-in model service providers. Choose a model service provider as needed, obtain the provider's API key, and fill in the key in the model service to manage models. This topic uses Alibaba Cloud Model Studio's qwen-max model, which requires you to obtain an API key before use.
2. Default Model: Set the default model. You can also select a model on the conversation page.
3. MCP Server: Add a server. The name and description can be customized. Select SSE for the type. The URL format is http://server_ip:port/sse. The default port for Python is 8001, and the default port for Java is 8080. When you first enter the MCP server settings page, you need to install UV and Bun as prompted.
  Important
  If you are using ECS, add security group rules to allow access to the custom TCP port in the inbound rules. The destination port must be the port on which the MCP service is running.
Select the MCP server on the conversation page.

Have a conversation with the assistant to write documents to Tablestore.

View the MCP call logs on the server.

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.

You can also view the written data in the Tablestore console.

Have a conversation with the assistant to retrieve relevant documents from Tablestore.

View the MCP call logs on the server.

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

Local debugging and custom development

Run the MCP source code locally in your IDE and use the MCP Inspector tool for debugging.

Step 1: Configure environment variables

Before running the code, you need to configure system environment variables. After configuration, restart or refresh your compilation and runtime environment, including IDE, command-line interface, other desktop applications, and background services to ensure that the latest system environment variables are successfully loaded.

Linux

Execute the following commands in the command-line interface to append environment variable settings to the ~/.bashrc file.

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

Run the following command to apply the changes:
```
source ~/.bashrc
```

Run the following commands to check whether the environment variables take effect:

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

macOS

Run the following command in the terminal to check the default Shell type.
```
echo $SHELL
```

Perform operations based on the default Shell type.

Zsh

Run the following commands to append environment variable settings to the ~/.zshrc file.

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

Run the following command to apply the changes:
```
source ~/.zshrc
```

Run the following commands to check whether the environment variables take effect:

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

Bash

Run the following commands to append environment variable settings to the ~/.bash_profile file.

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

Run the following command to apply the changes:
```
source ~/.bash_profile
```

Run the following commands to check whether the environment variables take effect:

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

Windows

CMD

Run the following commands in CMD to set environment variables.

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"

After restarting CMD, run the following commands to check whether the environment variables take effect:

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

PowerShell

Run the following commands in 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)

Run the following commands to check whether the environment variables take effect:

[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)

Step 2: Run the source code

Python

The environment requirements for running MCP source code locally are:

Python 3.10 or later.
PyCharm 2024.3.2 or later.
Configure the uv environment in PyCharm.

After completing the environment configuration, open the MCP source code directory tablestore-python-mcp-server in PyCharm and run the src/tablestore_mcp_server/main.py file. When the service runs successfully, the console will print the following logs.

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

Java

The environment requirement for running MCP source code locally is: JDK17.

After completing the environment configuration, open the MCP source code directory tablestore-java-mcp-server in IDEA and run the src/main/java/com.alicloud.openservices.tablestore.sample/App.java file. When the service runs successfully, the console will print the following logs.

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)

Step 3: Tool debugging

Install Node.js.
Run the following command in the terminal tool, enter y when prompted, and run MCP Inspector.
```
npx @modelcontextprotocol/inspector node build/index.js
```
The first run requires downloading the tool. Wait for a while. When the service runs successfully, the terminal will print the following content. The port depends on the actual running situation.
```
MCP Inspector is up and running at:
   http://localhost:6274
```
Access the URL output by the terminal in your browser to enter the MCP Inspector management page. Then select the transmission type according to your local running situation, fill in the URL, and click Connect to connect to the MCP service. Click List Tools to view the tools available for debugging.
Select the tablestore-store tool, enter content in information, and click Run Tool to write data to Tablestore.
View logs in the IDE console or log in to the Tablestore console to view the data.
Select the tablestore-search tool, enter the query content and size (number of data entries to return) in query, and click Run Tool to query data in Tablestore.

Upgrade Python version

This section describes how to upgrade the Python version using Python 3.13.2 as an example.

Download Python.
```
wget https://www.python.org/ftp/python/3.13.2/Python-3.13.2.tgz
```
If you cannot download due to network issues, directly download Python-3.13.2 and upload it to your server.
Decompress the package.
```
tar -zxvf Python-3.13.2.tgz
```

Install dependencies.

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

Navigate to the Python directory.
```
cd Python-3.13.2
```
Configure the installation path.
```
./configure
```
Compile Python.
```
make
```
Install Python.
```
make install
```
Check the installed version.
1. Check the Python version.
```
python3 --version
```
2. Check the Pip version.
```
pip3 --version
```

Tablestore:Quick start for Tablestore MCP service

Background

Preparations

Procedure

Step 1: Download the source code

Step 2: Run the service

Python

Java

Step 3: Use the MCP service

Local debugging and custom development

Step 1: Configure environment variables

Linux

macOS

Zsh

Bash

Windows

CMD

PowerShell

Step 2: Run the source code

Python

Java

Step 3: Tool debugging

Upgrade Python version

References