seekdb mcp server

December 25, 2025 · View on GitHub

English | 简体中文

seekdb mcp server

A Model Context Protocol (MCP) server that enables interaction with seekdb database. This server allows AI assistants to perform vector operations, manage collections, execute SQL queries and leverage AI functions through a controlled interface, making database exploration and analysis safer and more structured.

📋 Table of Contents

✨ Features

  • Vector Collection Management: Create, list, query, and manage vector collections
  • Advanced Search: Full-text search, vector similarity search, and hybrid search
  • AI Functions: Integrate with AI models for embedding, completion, and reranking
  • AI Memory System: Persistent vector-based memory for AI assistants
  • Data Import/Export: Import CSV files to seekdb and export data to CSV
  • SQL Operations: Execute SQL queries on seekdb
  • Multi-Transport: Support for stdio, SSE, and Streamable HTTP modes

🛠️ Available Tools

Vector Collection Tools

ToolDescription
create_collectionCreate a new vector collection with configurable dimension and distance metric
list_collectionsList all collections in seekdb
has_collectionCheck if a collection exists
peek_collectionPreview documents in a collection
add_data_to_collectionAdd documents with auto-generated embeddings
update_collectionUpdate existing documents in a collection
delete_documentsDelete documents by ID or filter conditions
query_collectionQuery documents using vector similarity search
delete_collectionDelete a collection and all its data

Search Tools

ToolDescription
full_text_searchPerform full-text search using MATCH...AGAINST syntax
hybrid_searchCombine full-text search and vector search with RRF ranking

AI Model Tools

ToolDescription
create_ai_modelRegister an AI model (embedding, completion, or rerank)
create_ai_model_endpointCreate an endpoint connecting a model to an API service
drop_ai_modelRemove a registered AI model
drop_ai_model_endpointRemove an AI model endpoint
ai_completeCall an LLM for text generation
ai_rerankRerank documents by relevance using an AI model
get_registered_ai_modelsList all registered AI models
get_ai_model_endpointsList all AI model endpoints

Memory Tools

ToolDescription
seekdb_memory_querySemantic search for stored memories
seekdb_memory_insertStore new memories with metadata
seekdb_memory_deleteDelete memories by ID
seekdb_memory_updateUpdate existing memories

Data Import/Export Tools

ToolDescription
import_csv_file_to_seekdbImport CSV data as a table or vector collection
export_csv_file_from_seekdbExport table or collection data to CSV

Database Tools

ToolDescription
execute_sqlExecute SQL queries on seekdb
get_current_timeGet current time from seekdb database

📋 Prerequisites

seekdb Requirements

seekdb supports two deployment modes:

  • Embedded Mode: seekdb runs as a library inside your application

    • Supported OS: Linux (glibc >= 2.28)
    • Supported Python: 3.11 to 3.13 (pyseekdb), CPython 3.8 to 3.14 (pylibseekdb)
    • Supported Architecture: x86_64, aarch64
    • Deployment: Deploy using the pyseekdb SDK

  • Client/Server Mode: Connect to a deployed seekdb

    • Deploy using yum install
    • Deploy in a container environment
    • Deploy using OceanBase Desktop (GUI application)

For detailed deployment instructions, see the seekdb Deployment Overview.

🚀 Installation

uv is an extremely fast Python package installer and resolver. The uvx command (included with uv) is used to run Python tools.

# On macOS and Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# On Windows
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# Or install via pip
pip install uv

After installation, restart your terminal or run source ~/.bashrc (or equivalent) to ensure uvx is available.

Install seekdb mcp server

Install from PyPI:

pip install seekdb-mcp-server

Or install from source:

git clone https://github.com/oceanbase/awesome-oceanbase-mcp.git
cd awesome-oceanbase-mcp/src/seekdb_mcp_server
pip install .

⚙️ Configuration

seekdb MCP Server supports two deployment modes:

Embedded Mode (Default)

No configuration required. The server automatically initializes an embedded seekdb database when started. This mode is recommended for local development and personal use.

Note: Embedded mode currently only supports Linux (glibc >= 2.28).

Server Mode

To connect to a deployed seekdb server, configure the following environment variables:

Method 1: Environment Variables

SEEKDB_HOST=localhost      # Database host
SEEKDB_PORT=2881           # Database port (default: 2881)
SEEKDB_USER=your_username
SEEKDB_PASSWORD=your_password
SEEKDB_DATABASE=your_database

Method 2: .env File

Copy .env.template to .env and fill in the values:

cp .env.template .env
# Edit .env with your seekdb connection details

Note: If SEEKDB_USER is not set, the server will automatically use embedded mode.

🚀 Quickstart

The seekdb MCP Server supports three transport modes:

Stdio Mode

Add the following content to your MCP client configuration file:

Embedded Mode (Using uvx):

{
  "mcpServers": {
    "seekdb": {
      "command": "uvx",
      "args": [
        "seekdb-mcp-server"
      ]
    }
  }
}

Server Mode (Using uvx with env):

{
  "mcpServers": {
    "seekdb": {
      "command": "uvx",
      "args": [
        "seekdb-mcp-server"
      ],
      "env": {
        "SEEKDB_HOST": "your_host",
        "SEEKDB_PORT": "2881",
        "SEEKDB_USER": "your_username",
        "SEEKDB_PASSWORD": "your_password",
        "SEEKDB_DATABASE": "your_database"
      }
    }
  }
}

Running from source:

{
  "mcpServers": {
    "seekdb": {
      "command": "uv",
      "args": [
        "--directory",
        "path/to/awesome-oceanbase-mcp/src/seekdb_mcp_server",
        "run",
        "seekdb-mcp-server"
      ]
    }
  }
}

SSE Mode

Start the server in SSE mode:

Step 1: Configure .env file in current directory

# Create .env file with your seekdb connection details
cat > .env << EOF
SEEKDB_HOST=your_host
SEEKDB_PORT=2881
SEEKDB_USER=your_username
SEEKDB_PASSWORD=your_password
SEEKDB_DATABASE=your_database
EOF

Step 2: Load environment variables

source .env

Step 3: Start the server

uvx seekdb-mcp-server --transport sse --port 6000

Parameters:

  • --transport: MCP server transport type (default: stdio)
  • --host: Host to bind to (default: 127.0.0.1, use 0.0.0.0 for remote access)
  • --port: Port to listen on (default: 6000)

Alternative startup (from source):

uv --directory path/to/seekdb_mcp_server run seekdb-mcp-server --transport sse --port 6000

Configuration URL: http://ip:port/sse

Client Configuration Examples

VSCode Extension Cline:

"sse-seekdb": {
  "autoApprove": [],
  "disabled": false,
  "timeout": 60,
  "type": "sse",
  "url": "http://127.0.0.1:6000/sse"
}

Cursor:

"sse-seekdb": {
  "autoApprove": [],
  "disabled": false,
  "timeout": 60,
  "type": "sse",
  "url": "http://127.0.0.1:6000/sse"
}

Cherry Studio:

  • MCP → General → Type: Select "Server-Sent Events (sse)" from dropdown
  • URL: http://127.0.0.1:6000/sse

Streamable HTTP

Start the server in Streamable HTTP mode:

Step 1: Configure .env file in current directory

# Create .env file with your seekdb connection details
cat > .env << EOF
SEEKDB_HOST=your_host
SEEKDB_PORT=2881
SEEKDB_USER=your_username
SEEKDB_PASSWORD=your_password
SEEKDB_DATABASE=your_database
EOF

Step 2: Load environment variables

source .env

Step 3: Start the server

uvx seekdb-mcp-server --transport streamable-http --port 6000

Parameters:

  • --transport: MCP server transport type (default: stdio)
  • --host: Host to bind to (default: 127.0.0.1, use 0.0.0.0 for remote access)
  • --port: Port to listen on (default: 6000)

Alternative startup (from source):

uv --directory path/to/seekdb_mcp_server run seekdb-mcp-server --transport streamable-http --port 6000

Configuration URL: http://ip:port/mcp

Client Configuration Examples

VSCode Extension Cline:

"streamable-seekdb": {
  "autoApprove": [],
  "disabled": false,
  "timeout": 60,
  "type": "streamableHttp",
  "url": "http://127.0.0.1:6000/mcp"
}

Cursor:

"streamable-seekdb": {
  "autoApprove": [],
  "disabled": false,
  "timeout": 60,
  "type": "streamableHttp",
  "url": "http://127.0.0.1:6000/mcp"
}

Cherry Studio:

  • MCP → General → Type: Select "Streamable HTTP (streamableHttp)" from dropdown
  • URL: http://127.0.0.1:6000/mcp

🔧 Advanced Features

🧠 AI Memory System

The AI Memory System enables your AI assistant to maintain persistent vector-based memory powered by seekdb's vector capabilities.

The memory system allows your AI to maintain continuous context across conversations, eliminating the need to repeat personal preferences and information. Four intelligent tools work together to create a seamless memory experience:

  • seekdb_memory_query - Semantically search and retrieve contextual memories
  • seekdb_memory_insert - Automatically capture and store important conversations
  • seekdb_memory_delete - Remove outdated or unwanted memories
  • seekdb_memory_update - Evolve memories with new information over time

Memory System Features

  • ✅ Cross-Session Continuity - No need to reintroduce yourself
  • ✅ Intelligent Semantic Search - Understands related concepts and context
  • ✅ Personalized Experience - AI truly "knows" your preferences
  • ✅ Automatic Capture - Important information saved without manual effort
  • ✅ Multilingual Support - Store and query memories in any language

Memory Categories

The memory system intelligently organizes information by category:

  • Sports/Fitness: football, basketball, swimming, gym, yoga, running, etc.
  • Food/Drinks: coffee, tea, pizza, sushi, vegan preferences, etc.
  • Work/Career: job, position, company, skills, projects, etc.
  • Personal: birthday, hometown, family, languages, hobbies, etc.
  • Technology: programming languages, frameworks, databases, tools, etc.
  • Entertainment: movies, music, books, games, genres, etc.

📚 Examples

Collection Operations

User: Create a Collection named "document"

AI: I've successfully created a collection named "document" in seekdb with the following default settings:

  • Dimension: 384 (vector size)
  • Distance metric: L2 (Euclidean distance)

User: Insert two sentences into the document: Machine learning is a subset of artificial intelligence, and vector databases enable semantic search

AI: Done! I've inserted two sentences into the "document" collection:

IDDocument
doc1Machine learning is a subset of artificial intelligence
doc2vector databases enable semantic search

User: Query documents related to machine learning

AI: Here are the documents related to "machine learning", ranked by relevance:

RankIDDocumentDistance
1doc1Machine learning is a subset of artificial intelligence5.44
2doc2vector databases enable semantic search7.83

User: Update the document about machine learning to "Python is a popular programming language."

AI: Done! I've updated the document:

IDBeforeAfter
doc1Machine learning is a subset of artificial intelligencePython is a popular programming language.

User: Delete the document about vector database

AI: Done! I've deleted the document about vector databases:

IDDeleted Document
doc2vector databases enable semantic search

User: Query all documents in the document

AI: Here are all the documents in the "document" collection:

IDDocumentMetadata
doc1Python is a popular programming language.{}

The collection currently contains 1 document.

User: Delete the collection document

AI: Done! The collection "document" has been permanently deleted along with all its data.

Search Tools

User: Create a collection, hybrid_search_test

AI: Done! The collection hybrid_search_test has been created successfully with:

  • Dimension: 384
  • Distance metric: L2

User: Insert the following documents:

  • "The weather forecast predicts sunny skies for the weekend."
  • "Mount Everest is the highest mountain peak in the world."
  • "Ocean waves crash against the rocky shoreline at sunset."
  • "Apple is a delicious red fruit that grows on trees in orchards."
  • "The new iPhone 17 Pro features an advanced camera system and titanium design."

AI: Done! Successfully added 5 documents to the hybrid_search_test collection:

IDDocument
doc1The weather forecast predicts sunny skies for the weekend.
doc2Mount Everest is the highest mountain peak in the world.
doc3Ocean waves crash against the rocky shoreline at sunset.
doc4Apple is a delicious red fruit that grows on trees in orchards.
doc5The new iPhone 17 Pro features an advanced camera system and titanium design.

User: Perform a hybrid_search, full-text keyword "apple", semantic search "apple smartphone technology"

AI: Here are the hybrid search results combining full-text keyword "apple" and semantic query "apple smartphone technology":

RankIDDocument
1doc4Apple is a delicious red fruit that grows on trees in orchards.
2doc5The new iPhone 17 Pro features an advanced camera system and titanium design.
3doc2Mount Everest is the highest mountain peak in the world.
4doc1The weather forecast predicts sunny skies for the weekend.
5doc3Ocean waves crash against the rocky shoreline at sunset.

Analysis:

  • doc4 ranks first due to the strong full-text match with the literal word "Apple"
  • doc5 ranks second because it matches semantically with "smartphone technology" (iPhone is an Apple smartphone), even though it doesn't contain the word "apple" explicitly
  • The remaining documents have lower relevance scores as they don't match either search criterion well

The hybrid search successfully combined keyword matching (BM25) with semantic similarity (vector search) using Reciprocal Rank Fusion (RRF) to produce these ranked results.

🔒 Security

This MCP server uses embedded seekdb by default, which runs locally within your application.

Security Best Practices

  1. Local Data Storage: Embedded seekdb stores data locally, ensuring data privacy
  2. Network Security: When using SSE or Streamable HTTP modes, ensure proper network security measures
  3. File Permissions: Ensure proper file permissions for the data directory

Security Checklist

  • ✅ Data stays local with embedded mode
  • ✅ No credentials required for embedded mode
  • ✅ Stdio mode: No network ports exposed
  • ✅ SSE/HTTP modes: Use --host 127.0.0.1 to restrict access to localhost only
  • ✅ Standard file system security applies

📄 License

Apache License - see LICENSE file for details.

🤝 Contributing

We welcome contributions! Please follow these steps:

  1. Fork the repository
  2. Create your feature branch 
    git checkout -b feature/amazing-feature
  3. Commit your changes 
    git commit -m 'Add some amazing feature'
  4. Push to the branch 
    git push origin feature/amazing-feature
  5. Open a Pull Request