Tablestore MCP Server Quick Start - Tablestore - Alibaba Cloud Documentation Center

Tablestore integrates the MCP protocol and provides an efficient data storage and retrieval solution using hybrid vector and scalar search capabilities. The following describes how to use the Tablestore MCP service.

Function Introduction

The Tablestore MCP service provides two tools:

Storage tool (tablestore-store): Converts input text into vectors using an embedding model (default: BAAI/bge-base-zh-v1.5) and writes both the original text and its vector representation into Tablestore.
Search tool (tablestore-search): Converts a query text into a vector using an embedding model, then retrieves relevant results from Tablestore’s search index using hybrid vector and scalar queries.

What are the advantages of using Tablestore as a vector database?

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

Hybrid queries: Natively supports hybrid vector and scalar queries. Its search index enables rich querying capabilities—including queries on any column (primary key or non-primary key), boolean queries, geo queries, full-text indexes, fuzzy queries, nested queries, deduplication, sorting, total row count, and statistical aggregation—to meet complex business requirements.
Rapid deployment and full lifecycle support: Offers standardized API operations and SQL queries. Integrates seamlessly with mainstream open-source frameworks such as LangChain, LlamaIndex, PAI-RAG, LangEngine, LangChain4J, Dify, and MCP to significantly accelerate development and time-to-value.
Ecosystem integration: Seamlessly connects with Alibaba Cloud’s big data ecosystem, including services like RDS, Flink, and MaxCompute, eliminating data silos.
Serverless: Delivers a serverless experience, removing the burden of hardware and software O&M and scaling so you can focus on business innovation and rapid iteration.
Low cost: Uses a pay-as-you-go billing method and a storage-compute disaggregation architecture, so you never pay for idle resources.
Scalability: Handles petabyte-scale data with automatic horizontal sharding and elastic resource scheduling.

Preparations

Activate Tablestore and create an instance.
Create an AccessKey for your Alibaba Cloud account or a Resource Access Management (RAM) user with Tablestore access permissions.
Prepare a server to deploy the MCP Server. You can use Alibaba Cloud ECS.

Note
The example uses an ECS instance running Alibaba Cloud Linux 3.2104 LTS 64-bit, Python 3.13.2, and Java 17.0.15.

Usage Steps

Step 1: Download the source code

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

Step 2: Run the service

Tablestore provides MCP services in both Python and Java versions.

Python

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

Alibaba Cloud Linux 3.2104 LTS 64-bit ships with Python 3.6.8 by default. For instructions on upgrading Python, see Upgrade Python version.

Go to the MCP source 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
```

Set 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 below.

Variable name	Description
HF_ENDPOINT	HuggingFace endpoint.
TABLESTORE_ACCESS_KEY_ID	AccessKey ID of your Alibaba Cloud account or RAM user.
TABLESTORE_ACCESS_KEY_SECRET	AccessKey secret of your Alibaba Cloud account or RAM user.
TABLESTORE_ENDPOINT	Endpoint of your Tablestore instance. If you use ECS, choose the endpoint based on region: If ECS and Tablestore are in the same region: use either the public network address or VPC address. If ECS and Tablestore are in different regions: use the public network address. Important Newly created Tablestore instances do not enable public network access by default. To use a public endpoint, go to the Tablestore console, navigate to Instance Management > Network Management, select Allowed Network Type, check Internet, and click Configure to save.
TABLESTORE_INSTANCE_NAME	Name of your Tablestore instance.

Additional optional environment variables

Variable name	Description
SERVER_PORT	Port for the service. Default: 8001.
TABLESTORE_TABLE_NAME	Name of the Tablestore data table. Default: ts_mcp_server_py_v1.
TABLESTORE_INDEX_NAME	Name of the search index on the Tablestore table. Default: ts_mcp_server_py_index_v1.
TABLESTORE_VECTOR_DIMENSION	Vector dimensions. Default: 768. Must match the embedding model’s output dimension.
TABLESTORE_TEXT_FIELD	Name of the text field. Default: _content.
TABLESTORE_VECTOR_FIELD	Name of the vector field. Default: _embedding.
EMBEDDING_PROVIDER_TYPE	Embedding model provider. Currently supports only hugging_face.
EMBEDDING_MODEL_NAME	Name of the embedding model. Default: BAAI/bge-base-zh-v1.5. The model’s vector dimension must match TABLESTORE_VECTOR_DIMENSION.
TOOL_STORE_DESCRIPTION	Enter a description for the tool.
TOOL_SEARCH_DESCRIPTION	Description for the search tool.

Run the MCP service.
```
uv run tablestore-mcp-server
```
The first run downloads dependencies. Wait patiently. If the download fails due to network issues, rerun the command. Upon successful execution, you will see logs like:
```
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 JDK 17.

Install JDK.

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

Go to the MCP source directory.

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

Compile the source code.

./mvnw package -DskipTests -s settings.xml

Upon successful compilation, you will see logs like:

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

Set 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 below.

Variable name	Description
HF_ENDPOINT	HuggingFace mirror endpoint.
TABLESTORE_ACCESS_KEY_ID	AccessKey ID of your Alibaba Cloud account or RAM user.
TABLESTORE_ACCESS_KEY_SECRET	AccessKey secret of your Alibaba Cloud account or RAM user.
TABLESTORE_ENDPOINT	Endpoint of your Tablestore instance. If you use ECS, choose the endpoint based on region: If ECS and Tablestore are in the same region: use either the public network address or VPC address. If ECS and Tablestore are in different regions: use the public network address. Important Newly created Tablestore instances do not enable public network access by default. To use a public endpoint, go to the Tablestore console, navigate to Instance Management > Network Management, select Allowed Network Type, check Internet, and click Configure to save.
TABLESTORE_INSTANCE_NAME	Name of your Tablestore instance.

Additional optional environment variables

Variable name	Description
SERVER_PORT	Port for the service. Default: 8080.
TABLESTORE_TABLE_NAME	Name of the Tablestore data table. Default: tablestore_java_mcp_server_v1.
TABLESTORE_INDEX_NAME	Name of the search index on the Tablestore table. Default: tablestore_java_mcp_server_index_v1.
TABLESTORE_TABLE_PK_NAME	Name of the primary key column. Default: id.
TABLESTORE_VECTOR_DIMENSION	Vector dimensions. Default: 768. Must match the embedding model’s output dimension.
TABLESTORE_TEXT_FIELD	Name of the text field. Default: _content.
TABLESTORE_VECTOR_FIELD	Name of the vector field. Default: _embedding.
EMBEDDING_MODEL_NAME	Name of the embedding model. Default: ai.djl.huggingface.rust/BAAI/bge-base-en-v1.5/0.0.1/bge-base-en-v1.5. The model’s vector dimension must match TABLESTORE_VECTOR_DIMENSION.

Run the MCP service.

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

Upon successful execution, you will see logs like:

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 includes multiple model providers. Select one based on your needs, obtain its API key, and enter the key in Model Service to manage models. This example uses qwen-max from Alibaba Cloud Model Studio. Before using it, get an API key.
2. Default model: Set a default model, or choose one during a conversation.
  
  In the message input toolbar, click the @ icon to open the model selection panel. You can choose Alibaba Cloud Model Studio models such as qwen-vl-plus, qwen-coder-plus, qwen-turbo, qwen-plus, and qwen-max.
3. MCP server: Click Add Server. You can customize the name and description. Set Type to SSE. The URL format is http://server_ip:port/sse. The default port is 8001 for Python and 8080 for Java. On your first visit to the MCP server settings page, install UV and Bun as prompted.
  
  Important
  If you use ECS, add a security group rule. In the inbound rules, allow custom TCP traffic to the port used by the MCP service.
  
  In the Request Headers section, set Content-Type=application/json and Authorization=Bearer token.
Select the MCP server in the chat interface.

Click the green terminal icon in the bottom toolbar. A panel appears showing that Tablestore is connected successfully. The connection address appears as http://<IP address>:8001/sse. A green checkmark indicates a healthy connection.
Chat with the assistant to write a document into Tablestore.

Enter a question such as What are the basic billing methods for Alibaba Cloud ECS? Please generate a document and write it to Tablestore. The assistant’s reply shows a tablestore-store tool call card with status Completed ✓, indicating the document was successfully written to Tablestore via the MCP tool.

You can view the MCP call log 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.

On the Data Management tab of table ts_mcp_server_py_v1, you see the inserted row containing columns id (primary key), _content, _embedding, and title, confirming successful storage.

Chat with the assistant to retrieve relevant documents from Tablestore.

The assistant’s reply shows a tablestore-search tool call status of "Completed ✓", indicating the MCP service successfully retrieved relevant documents from Tablestore and generated a response based on them.

You can view the MCP call log 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

You can run the MCP source code in your local IDE and debug it using the MCP Inspector tool.

Step 1: Configure environment variables

Before running the code, configure system environment variables. After configuration, restart or refresh your IDE, command-line interface, desktop applications, and background services to ensure the new environment variables take effect.

Linux

In the command-line interface, append the environment variables 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

Apply the changes.
```
source ~/.bashrc
```

Verify the environment variables.

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

macOS

In Terminal, check your default shell.
```
echo $SHELL
```

Proceed based on your shell type.

Zsh

Append environment variables to ~/.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

Apply the changes.
```
source ~/.zshrc
```

Verify the environment variables.

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

Bash

Append environment variables to ~/.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

Apply the changes.
```
source ~/.bash_profile
```

Run the following command to check whether the environment variable has taken effect.

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

Windows

CMD

In CMD, 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, verify the environment variables.

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

PowerShell

In PowerShell, run:

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

Verify the environment variables.

[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

Requirements for running the MCP source locally:

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

After configuring the environment, open the tablestore-python-mcp-server directory in PyCharm and run src/tablestore_mcp_server/main.py. Upon successful execution, the console prints:

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

Java

Requirements for running the MCP source locally: JDK 17.

After configuring the environment, open the tablestore-java-mcp-server directory in IDEA and run src/main/java/com.alicloud.openservices.tablestore.sample/App.java. Upon successful execution, the console prints:

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.
In your terminal, run the following command. Enter y when prompted to launch MCP Inspector.
```
npx @modelcontextprotocol/inspector node build/index.js
```
The first run downloads the tool. Wait a moment. Upon success, the terminal prints something like (port may vary):
```
MCP Inspector is up and running at:
   http://localhost:6274
```
In your browser, go to the address shown in the terminal to open the MCP Inspector dashboard. Choose a transport type and enter the URL, then click Connect to connect to the MCP service. Click List Tools to view available tools.

For example, set Transport Type to SSE and URL to http://localhost:8001/sse. After a successful connection, the status turns green ("Connected"). Clicking List Tools shows the registered tools: tablestore-store (stores documents in Tablestore for later retrieval) and tablestore-search (searches Tablestore for semantically similar documents using natural language).
Select the tablestore-store tool. Enter content in the information field and click Run Tool to write data to Tablestore.

You can view logs in your IDE console or log in to the Tablestore console to verify the data.

On the Data Management tab, you see one row inserted into table ts_mcp_server_py_v1, containing three columns: id (primary key), _content (text), and _embedding (vector), confirming successful insertion.
Select the tablestore-search tool. Enter a query and size (number of results) in the query field, then click Run Tool to search Tablestore.

Upon success, the results show documents semantically similar to your query, including the matched text (_content) and similarity score (_score).

Upgrade Python version

The following steps show how to upgrade to Python 3.13.2.

Download Python.
```
wget https://www.python.org/ftp/python/3.13.2/Python-3.13.2.tgz
```
If network issues prevent downloading, directly download Python-3.13.2 and upload it to your server.
Extract the file.
```
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

Enter 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 Python version.
```
python3 --version
```
2. Check Pip version.
```
pip3 --version
```

Tablestore:Tablestore MCP Server

Function Introduction

Preparations

Usage Steps

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