Integrate OceanBase MCP Server with Cursor

The Model Context Protocol (MCP) was introduced and open-sourced by Anthropic in November 2024. It enables large language models to interact with external tools and data sources. With MCP, you don't need to copy model output and run it manually—the model can instruct tools to perform actions directly.

The OceanBase MCP Server uses MCP to let LLMs work with OceanBase Database and run SQL. With an MCP-capable client you can quickly prototype applications. The server is open source on GitHub.

Cursor is an AI-powered code editor that runs on Windows, macOS, and Linux.

This topic shows how to integrate the OceanBase MCP Server with Cursor to build a backend application quickly.

Prerequisites

• You have deployed OceanBase Database and created a MySQL-compatible tenant. For details, see Create a tenant.

• You have Python 3.11 or later and pip installed. If your system Python is older, use Miniconda to create a Python 3.11+ environment.

• You have Git installed for your OS.

• You have the Python package manager uv installed. Verify with:

  pip install uv
  uv --version
  

• You have Cursor installed for your OS. On first launch, sign up or log in. You can then create a new project or open an existing one.

Step 1: Get database connection details

Obtain the database connection string from your OceanBase deployment team or administrator. For example:

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

Parameters:

• $host: The IP for connecting to OceanBase. Use an ODP address when connecting via OceanBase Database Proxy (ODP), or an OBServer IP for direct connection.

• $port: The connection port. ODP default is 2883; direct connection default is 2881. Both can be customized at deployment.

• $database_name: The database to use.

  Notice

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

• $user_name: The tenant account. ODP: username@tenant#cluster or cluster:tenant:username. Direct: username@tenant.

• $password: The account password.

For more on connection strings, see Connect to an OceanBase tenant by using OBClient.

Step 2: Configure the OceanBase MCP Server

Clone the OceanBase MCP Server repository

Download the source:

git clone https://github.com/oceanbase/mcp-oceanbase.git

Change into the project directory:

cd mcp-oceanbase

Install dependencies

From the mcp-oceanbase directory:

uv venv
source .venv/bin/activate
uv pip install .

Create a Cursor project directory and configure the MCP Server

Create a folder for your Cursor project and open it in Cursor (e.g. cursor). Generated files will be placed here.

Open the chat with Ctrl + L (Windows) or Command + L (macOS). Click the gear icon in the top-right and select MCP Tools.

Add and configure MCP servers

1. Click Add Custom MCP and enter the configuration.

   

2. Paste the configuration below and confirm. Replace path/to/your/mcp-oceanbase/src/oceanbase_mcp_server with the absolute path to the oceanbase_mcp_server folder, and set OB_HOST, OB_PORT, OB_USER, OB_PASSWORD, and OB_DATABASE to your database values.

   {
   "mcpServers": {
       "oceanbase": {
       "command": "uv",
       "args": [
           "--directory", 
           "/path/to/your/mcp-oceanbase/src/oceanbase_mcp_server",
           "run",
           "oceanbase_mcp_server"
       ],
       "env": {
           "OB_HOST": "***",
           "OB_PORT": "***",
           "OB_USER": "***",
           "OB_PASSWORD": "***",
           "OB_DATABASE": "***"
       }
       }
   }
   }
   

3. When configuration succeeds, the server shows as Available.

   

Test the MCP Server

1. In the chat, ask: How many tables are in the test database? Cursor will show the SQL it plans to run. If it looks correct, click Run tool. Cursor will then list the tables in the test database, confirming the connection to OceanBase.

Build a RESTful API with FastAPI

You can use FastAPI to quickly create a REST-style API.

1. Create the customer table.

   In the chat: Create a customer table with primary key ID and columns name, age, telephone, and location. Confirm the SQL and click Run tool.

2. Insert test data.

   Prompt: Insert 10 rows into the customer table. Confirm the SQL and click Run tool. On success, you’ll see a message like Successfully inserted 10 test rows into the customer table.

3. Create the FastAPI project.

   Prompt: Create a FastAPI project that exposes a RESTful API for the customer table. Confirm and click Run tool.

   This step generates two files. For a first run, accepting all generated content is recommended; you can adjust it later as needed.

4. Create a virtual environment and install dependencies.

   In the project directory:

   uv venv
   source .venv/bin/activate
   uv pip install -r requirements.txt
   

5. Start the FastAPI app.

   uvicorn main:app --reload
   

6. Query the API.

   From a terminal or any HTTP client:

   curl http://127.0.0.1:8000/customers
   

   The response will contain the customer records like this:

   [{"id":1,"name":"Alice","age":28,"telephone":"1234567890","location":"Beijing"},{"id":2,"name":"Bob","age":32,"telephone":"2345678901","location":"Shanghai"},{"id":3,"name":"Charlie","age":25,"telephone":"3456789012","location":"Guangzhou"},{"id":4,"name":"David","age":40,"telephone":"4567890123","location":"Shenzhen"},{"id":5,"name":"Eve","age":22,"telephone":"5678901234","location":"Chengdu"},{"id":6,"name":"Frank","age":35,"telephone":"6789012345","location":"Wuhan"},{"id":7,"name":"Grace","age":30,"telephone":"7890123456","location":"Hangzhou"},{"id":8,"name":"Heidi","age":27,"telephone":"8901234567","location":"Nanjing"},{"id":9,"name":"Ivan","age":29,"telephone":"9012345678","location":"Tianjin"},{"id":10,"name":"Judy","age":31,"telephone":"0123456789","location":"Chongqing"}]
   

   The generated code implements full CRUD (create, read, update, delete) for the customer table:

   from fastapi import FastAPI, HTTPException, Depends
   from pydantic import BaseModel
   from typing import List
   from sqlalchemy import create_engine, Column, Integer, String
   from sqlalchemy.ext.declarative import declarative_base
   from sqlalchemy.orm import sessionmaker, Session
   
   # OceanBase connection configuration
   DATABASE_URL = "mysql://***:***@***:***/***"
   
   engine = create_engine(DATABASE_URL, echo=True)
   SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)
   Base = declarative_base()
   
   class Customer(Base):
       __tablename__ = "customer"
       id = Column(Integer, primary_key=True, index=True)
       name = Column(String(100))
       age = Column(Integer)
       telephone = Column(String(20))
       location = Column(String(100))
   
   class CustomerCreate(BaseModel):
       id: int
       name: str
       age: int
       telephone: str
       location: str
   
   class CustomerUpdate(BaseModel):
       name: str = None
       age: int = None
       telephone: str = None
       location: str = None
   
   class CustomerOut(BaseModel):
       id: int
       name: str
       age: int
       telephone: str
       location: str
       class Config:
           orm_mode = True
   
   def get_db():
       db = SessionLocal()
       try:
           yield db
       finally:
           db.close()
   
   app = FastAPI()
   
   @app.post("/customers/", response_model=CustomerOut)
   def create_customer(customer: CustomerCreate, db: Session = Depends(get_db)):
       db_customer = Customer(**customer.dict())
       db.add(db_customer)
       try:
           db.commit()
           db.refresh(db_customer)
       except Exception as e:
           db.rollback()
           raise HTTPException(status_code=400, detail=str(e))
       return db_customer
   
   @app.get("/customers/", response_model=List[CustomerOut])
   def read_customers(skip: int = 0, limit: int = 100, db: Session = Depends(get_db)):
       return db.query(Customer).offset(skip).limit(limit).all()
   
   @app.get("/customers/{customer_id}", response_model=CustomerOut)
   def read_customer(customer_id: int, db: Session = Depends(get_db)):
       customer = db.query(Customer).filter(Customer.id == customer_id).first()
       if customer is None:
           raise HTTPException(status_code=404, detail="Customer not found")
       return customer
   
   @app.put("/customers/{customer_id}", response_model=CustomerOut)
   def update_customer(customer_id: int, customer: CustomerUpdate, db: Session = Depends(get_db)):
       db_customer = db.query(Customer).filter(Customer.id == customer_id).first()
       if db_customer is None:
           raise HTTPException(status_code=404, detail="Customer not found")
       for var, value in vars(customer).items():
           if value is not None:
               setattr(db_customer, var, value)
       db.commit()
       db.refresh(db_customer)
       return db_customer
   
   @app.delete("/customers/{customer_id}")
   def delete_customer(customer_id: int, db: Session = Depends(get_db)):
       db_customer = db.query(Customer).filter(Customer.id == customer_id).first()
       if db_customer is None:
           raise HTTPException(status_code=404, detail="Customer not found")
       db.delete(db_customer)
       db.commit()
       return {"ok": True}