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.

Feature architecture

Core toolkits

OceanBase MCP Server provides standardized interfaces for AI tools to directly call database features:

Resource endpoints

Resource interfaces exposed through the MCP protocol for AI tools to directly call:

Prerequisites

• You have installed Cursor or another tool that supports the MCP protocol (such as Windsurf or Qwen Code).

• You have deployed an OceanBase cluster and created a MySQL-compatible user tenant. The user connecting to the user tenant must have the CREATE, INSERT, DROP, and SELECT privileges on the target database.

  • For more information about deploying an OceanBase cluster, see Deployment overview.
  • For more information about creating a user tenant, see Create a tenant.
  • For more information about user privileges, see Privilege types in MySQL-compatible mode.

• You have installed a Python environment (version 3.10 to 3.12).

  • You can download the Python installation package from the Python official website.

Procedure

Step 1: Obtain the database connection information

Contact the OceanBase Database deployment personnel or administrator to obtain the database connection string. For example:

obclient -h$host -P$port -u$user_name -p$password -D$database_name

Parameter description:

• $host: The IP address for connecting to OceanBase Database. For connection through OceanBase Database Proxy (ODP), use the ODP address. For direct connection, use the IP address of an OBServer node.

• $port: The port for connecting to OceanBase Database. For connection through ODP, the default value is 2883, which can be customized when ODP is deployed. For direct connection, the default value is 2881, which can be customized when OceanBase Database is deployed.

• $database_name: The name of the database to be accessed.

  Notice

  The user connecting to the tenant must have the CREATE, INSERT, DROP, and SELECT privileges on the database. For more information about user privileges, see Privilege types in MySQL-compatible mode.

• $user_name: The tenant connection account. For connection through ODP, the format is username@tenant name#cluster name or cluster name:tenant name:username. For direct connection, the format is username@tenant name.

• $password: The account password.

For more information about the connection string, see Connect to an OceanBase tenant by using OBClient.

Here is an example:

obclient -hxxx.xxx.xxx.xxx -P2881 -utest_user001@mysql001 -p****** -Dtest

Step 2: Install Python dependencies

Environment preparation

1. Install the uv package manager.

   • On macOS/Linux, run the following command:

     curl -LsSf https://astral.sh/uv/install.sh | sh
     

   • On Windows, run the following command:

     irm https://astral.sh/uv/install.ps1 | iex
     

   • Or use pip to install the uv package manager:

     pip install uv
     

2. Verify whether uv is installed successfully:

   uv --version
   

Install OceanBase MCP Server

1. Choose a directory and run the following command to create a virtual environment:

   uv venv
   

2. Run the following command to activate the virtual environment:

   source .venv/bin/activate
   

3. Run the following command to install OceanBase MCP Server:

   uv pip install oceanbase-mcp
   

Step 3: Configure the MCP Server environment

1. Create a .env file:

   cat > .env <<EOF
   OB_HOST=127.0.0.1
   OB_PORT=2881
   OB_USER=test_user001@mysql001  # Example: MySQL-compatible tenant user
   OB_PASSWORD=your_password
   OB_DATABASE=test
   EOF
   

2. Start the MCP Server:

   uv run oceanbase_mcp_server \
       --transport sse \           # Supports stdio/streamable-http/sse modes
       --host 0.0.0.0 \            # Allows external access; can be changed to 127.0.0.1 for local access only
       --port 8000                 # Custom port (adjust subsequent configuration if using e.g. 8001)
   

Step 4: Configure Cursor to connect to the MCP Server

1. Open the Cursor settings page: Click the gear icon in the upper-right corner → Select MCP → Click New MCP Server.

   

2. Edit the mcp.json configuration:

   {
     "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"  # Must match the port from Step 3
       }
     }
   }
   

3. Verify the connection.

   After saving, return to the MCP page, where you can see the newly added MCP.

4. After adding, when you ask questions in the Chat window, Cursor will automatically use the MCP tools.

   

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

   Analyze the customer data and show the distribution of customers by country.
   

2. Cursor execution process:

   1. Cursor calls execute_sql to execute the aggregation query:

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