Initial commit
This commit is contained in:
Zhongwei Li
@@ -0,0 +1,248 @@
|
||||
---
|
||||
|
||||
slug: /oceanbase-mcp-server-and-ai-tool-integration-guide
|
||||
---
|
||||
|
||||
# OceanBase MCP Server
|
||||
|
||||
## Background information
|
||||
|
||||
AI tools are evolving rapidly, from graphical solutions like Cursor, Windsurf, and Trae to command-line options such as Claude Code, Gemini CLI, and Qwen Code. Empowered by Agent-based frameworks, these tools are remarkably capable. However, a key limitation remains: AI tools cannot directly access databases, leaving a gap between data and analysis. The MCP protocol bridges this gap. By leveraging the MCP protocol, OceanBase MCP Server enables AI tools to interact directly with databases and retrieve data seamlessly.
|
||||
|
||||
Traditionally, data analysis tasks—such as user analytics, product analysis, order tracking, and user behavior analysis—require developers to build backend systems for data retrieval and frontend interfaces for data visualization. Even with BI tools, some familiarity with SQL is often necessary. While data can be displayed, understanding the underlying logic or making business decisions based on that data still depends on the expertise of data analysts.
|
||||
|
||||
The combination of AI tools, MCP, and large language models (LLMs) is transforming the way data analysis is performed. Analysts no longer need to rely on developers or have SQL knowledge. They can simply describe their requirements to AI tools and instantly receive the results they need—complete with attractive charts and initial data insights.
|
||||
|
||||
## Functional architecture
|
||||
|
||||
### Core toolkit
|
||||
|
||||
OceanBase MCP Server offers standardized interfaces that enable AI tools to interact directly with the database:
|
||||
|
||||
| Tool | Description |
|
||||
|-----------------------------|-------------|
|
||||
| `execute_sql` | Executes any SQL statement (such as `SELECT`, `INSERT`, `UPDATE`, `DELETE`, `DDL`). |
|
||||
| `get_ob_ash_report` | Gets seekdb Active Session History (ASH) reports for performance diagnostics. |
|
||||
| `get_current_time` | Returns the current time of the seekdb instance. |
|
||||
| `oceanbase_text_search` | Performs full-text searches across seekdb database tables. |
|
||||
| `oceanbase_vector_search` | Executes vector similarity searches within seekdb database tables. |
|
||||
| `oceanbase_hybrid_search` | Conducts hybrid searches, combining relational filtering with vector search. |
|
||||
| `ob_memory_query` | Retrieves historical conversation records from the AI memory system using semantic search. (AI Memory System Tool) |
|
||||
| `ob_memory_insert` | Automatically captures and stores important conversation content to build a knowledge base. (AI Memory System Tool) |
|
||||
| `ob_memory_delete` | Deletes outdated or redundant conversation memories. (AI Memory System Tool) |
|
||||
| `ob_memory_update` | Updates or evolves memory content based on new information. (AI Memory System Tool) |
|
||||
|
||||
### Resource endpoints
|
||||
|
||||
AI tools can directly access these resource endpoints via the MCP protocol:
|
||||
|
||||
| Resource path | Description |
|
||||
|--------------------------------|-------------|
|
||||
| `oceanbase://tables` | Lists all tables in the database. |
|
||||
| `oceanbase://sample/{table}` | Retrieves sample data (first 100 rows) from the specified table. `{table}` can be dynamically replaced with the actual table name. |
|
||||
|
||||
## Prerequisites
|
||||
|
||||
* You have installed Cursor or another tool that supports the MCP protocol (such as Windsurf or Qwen Code).
|
||||
* You have deployed seekdb.
|
||||
|
||||
* For deployment details, see [Deploy seekdb](../../400.guides/400.deploy/100.prepare-servers.md).
|
||||
|
||||
* You have a Python environment set up (version 3.10 to 3.12).
|
||||
|
||||
* Download the Python installer from the [official Python website](https://www.python.org/downloads/).
|
||||
|
||||
## Procedure
|
||||
|
||||
### Step 1: Obtain database connection information
|
||||
|
||||
Contact the database administrator or deployment team to get the required database connection string. For example:
|
||||
|
||||
```sql
|
||||
obclient -h$host -P$port -u$user_name -p$password -D$database_name
|
||||
```
|
||||
|
||||
**Parameters:**
|
||||
|
||||
* `$host`: The IP address for connecting to seekdb.
|
||||
* `$port`: The port number for connecting to seekdb. Default is `2881`.
|
||||
* `$database_name`: The name of the database to access.
|
||||
* `$user_name`: The account for connecting to the instance. Default is `root`.
|
||||
* `$password`: The account password. Default is empty.
|
||||
|
||||
**Here is an example:**
|
||||
|
||||
```shell
|
||||
obclient -hxxx.xxx.xxx.xxx -P2881 -uroot -p****** -Dtest
|
||||
```
|
||||
|
||||
### Step 2: Install Python dependencies
|
||||
|
||||
#### Environment setup
|
||||
|
||||
1. Install the uv package manager.
|
||||
|
||||
* On macOS or Linux, run:
|
||||
|
||||
```shell
|
||||
curl -LsSf https://astral.sh/uv/install.sh | sh
|
||||
```
|
||||
|
||||
* On Windows, run:
|
||||
|
||||
```shell
|
||||
irm https://astral.sh/uv/install.ps1 | iex
|
||||
```
|
||||
|
||||
* Alternatively, you can install uv using pip:
|
||||
|
||||
```shell
|
||||
pip install uv
|
||||
```
|
||||
|
||||
2. Verify the installation:
|
||||
|
||||
```shell
|
||||
uv --version
|
||||
```
|
||||
|
||||
#### Install OceanBase MCP Server
|
||||
|
||||
1. Choose a directory and create a virtual environment:
|
||||
|
||||
```shell
|
||||
uv venv
|
||||
```
|
||||
|
||||
2. Activate the virtual environment:
|
||||
|
||||
```shell
|
||||
source .venv/bin/activate
|
||||
```
|
||||
|
||||
3. Install OceanBase MCP Server:
|
||||
|
||||
```shell
|
||||
uv pip install oceanbase-mcp
|
||||
```
|
||||
|
||||
### Step 3: Configure the MCP Server environment
|
||||
|
||||
1. Create a `.env` file with your database connection info:
|
||||
|
||||
```shell
|
||||
cat > .env <<EOF
|
||||
OB_HOST=127.0.0.1
|
||||
OB_PORT=2881
|
||||
OB_USER=root
|
||||
OB_PASSWORD=your_password
|
||||
OB_DATABASE=test
|
||||
EOF
|
||||
```
|
||||
|
||||
2. Start the MCP Server:
|
||||
|
||||
```shell
|
||||
uv run oceanbase_mcp_server \
|
||||
--transport sse \ # Supports stdio/streamable-http/sse modes
|
||||
--host 0.0.0.0 \ # Allows external access, use 127.0.0.1 for local access only
|
||||
--port 8000 # Custom port (update later configs if changed)
|
||||
```
|
||||
|
||||
### Step 4: Connect Cursor to the MCP Server
|
||||
|
||||
1. Use Cursor V2.0.64 as an example. Click the **Open Settings** icon in the upper right corner, select **Tools & MCP**, and click **New MCP Server**.
|
||||
|
||||
|
||||
|
||||
2. Edit the `mcp.json` configuration file:
|
||||
|
||||
```shell
|
||||
{
|
||||
"mcpServers": {
|
||||
"ob-sse": {
|
||||
"autoApprove": [],
|
||||
"disabled": false, # Must be set to false to enable the service
|
||||
"timeout": 60,
|
||||
"type": "sse",
|
||||
"url": "http://127.0.0.1:8000/sse" # Make sure this matches the port you set in Step 3
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
3. Verify the connection.
|
||||
|
||||
After saving the configuration, return to the **Tools & MCP** page. Then you will find the newly added MCP server.
|
||||
|
||||
4. Once added, Cursor will automatically use MCP tools when you ask questions in the Chat window.
|
||||
|
||||
|
||||
|
||||
## Quick start examples
|
||||
|
||||
Once you set up seekdb and the MCP Server, you can quickly try out data analysis capabilities. The following examples use the [Online Retail Dataset](https://www.kaggle.com/datasets/ulrikthygepedersen/online-retail-dataset) and Cursor to demonstrate how AI tools can seamlessly work with the OceanBase MCP Server for common analytics tasks.
|
||||
|
||||
### Customer distribution analysis
|
||||
|
||||
1. Instruction input:
|
||||
|
||||
```
|
||||
Please analyze the customer data and show the distribution of customers by country.
|
||||
```
|
||||
|
||||
2. Cursor execution process:
|
||||
|
||||
1. Cursor calls `execute_sql` to run an aggregation query:
|
||||
|
||||
```sql
|
||||
SELECT Country,
|
||||
COUNT(DISTINCT CustomerID) AS customer_count
|
||||
FROM dataanalysis_english.invoice_items
|
||||
WHERE CustomerID IS NOT NULL
|
||||
AND Country IS NOT NULL
|
||||
GROUP BY Country
|
||||
ORDER BY customer_count DESC;
|
||||
```
|
||||
|
||||
2. Cursor automatically generates a structured analysis result.
|
||||
|
||||
|
||||
|
||||
3. Further request:
|
||||
|
||||
```
|
||||
Please convert the above results into a table.
|
||||
```
|
||||
|
||||
4. Output:
|
||||
|
||||
|
||||
|
||||
### Best-selling products analysis
|
||||
|
||||
1. Instruction input:
|
||||
|
||||
```
|
||||
Find the most popular products and show their sales performance.
|
||||
```
|
||||
|
||||
2. Output:
|
||||
|
||||
Cursor summarizes the most popular products with performance insights and displays them in a ranked table or bar chart.
|
||||
|
||||
|
||||
|
||||
### Sales trend over time
|
||||
|
||||
1. Instruction input:
|
||||
|
||||
```
|
||||
Analyze monthly sales trends and identify peak periods.
|
||||
```
|
||||
|
||||
2. Output:
|
||||
|
||||
Cursor generates a line chart showing monthly sales trends with peak periods highlighted (for example, November and December for holiday shopping).
|
||||
|
||||
|
||||
Reference in New Issue
Block a user