mochow-mcp-server 2.4.1

MCP server for Mochow vector database

百度向量数据库MCP Server

本代码仓库包含一个 MCP 服务器，它提供对百度云向量数据库功能的访问。

前提条件

在使用百度云向量数据库MCP Server之前，请确保你具备以下条件：

1. Python 3.10 或更高版本
2. 已安装uv用于运行MCP Server
3. 项目依赖由 uv 根据 pyproject.toml 自动安装，其中 pymochow 固定为 2.4.1

使用方式

使用百度云向量数据库MCP Server的推荐方式是通过uv运行，而无需进行安装。

克隆代码仓库，执行以下命令：

git clone https://github.com/baidu/mochow-mcp-server-python.git
cd mochow-mcp-server-python

随后，你可以直接通过uv运行，其中endpoint、user和api-key根据实际需要修改：

uv run src/mochow_mcp_server/server.py
uv run src/mochow_mcp_server/server.py --transport stdio --endpoint http://127.0.0.1:8287 --user root --api-key mochow

或者，将src/mochow_mcp_server/example.env复制为当前运行目录下的.env来设置环境变量。若从仓库根目录运行以下命令，.env应放在仓库根目录：

uv run src/mochow_mcp_server/server.py

非空环境变量会覆盖命令行参数；如果 .env 中已经设置了 MOCHOW_ENDPOINT、MOCHOW_USER、MOCHOW_API_KEY 或 MOCHOW_MCP_*，对应的命令行参数不会生效。

MCP协议

当前支持两种 MCP transport：

• stdio：默认协议，适合 Claude Desktop、Cursor 和本地 MCP client 以子进程方式启动。
• sse：HTTP SSE 协议，适合需要独立 MCP Server 进程并通过 HTTP 连接的 MCP client。

stdio 启动示例：

uv run src/mochow_mcp_server/server.py \
  --transport stdio \
  --endpoint http://127.0.0.1:8287 \
  --user root \
  --api-key mochow

SSE 启动示例：

uv run src/mochow_mcp_server/server.py \
  --transport sse \
  --host 127.0.0.1 \
  --port 8000 \
  --endpoint http://127.0.0.1:8287 \
  --user root \
  --api-key mochow

SSE 默认监听与路径：

• host：0.0.0.0
• port：8000
• SSE endpoint：/sse
• message endpoint：/messages/

可选运行参数：

• --transport: stdio 或 sse，默认 stdio
• --host: SSE 服务监听地址
• --port: SSE 服务监听端口
• --sse-path: SSE endpoint 路径
• --message-path: SSE message endpoint 路径
• --log-level: SSE transport 使用的 Uvicorn 日志级别

对应环境变量：

• MOCHOW_MCP_TRANSPORT
• MOCHOW_MCP_HOST
• MOCHOW_MCP_PORT
• MOCHOW_MCP_SSE_PATH
• MOCHOW_MCP_MESSAGE_PATH
• MOCHOW_MCP_LOG_LEVEL

SSE 会暴露 HTTP 服务；本地使用建议显式设置 --host 127.0.0.1，不要把未加鉴权的 MCP Server 直接暴露到不可信网络。

支持的应用程序

百度云向量数据库MCP Server可以与各种支持模型上下文协议的大语言模型应用程序配合使用：

• Claude Desktop：Anthropic 公司为 Claude 开发的桌面应用程序

• Cursor：支持 MCP 的人工智能代码编辑器

• 自定义 MCP 客户端：任何实现 MCP 客户端规范的应用程序

在Claude Desktop中的使用方式

从https://claude.ai下载 Claude Desktop。

打开 Claude Desktop 的配置文件，在 macOS 系统中，路径为~/Library/Application Support/Claude/claude_desktop_config.json。

添加以下配置：

{
    "mcpServers": {
        "mochow": {
            "command": "/PATH/TO/uv",
            "args": [
                "--directory",
                "/path/to/mochow-mcp-server-python",
                "run",
                "src/mochow_mcp_server/server.py",
                "--endpoint",
                "http://127.0.0.1:8287",
                "--user",
                "root",
                "--api-key",
                "mochow"
            ]
        }
    }
}

重启 Claude Desktop。

在 Cursor 中的使用方法

Cursor 也支持 MCP工具。你可以通过以下方式将百度MCP Server添加到Cursor中：

依次打开Cursor设置>功能>MCP，点击+添加新的MCP服务器按钮，在mcp.json中添加以下配置：

{
    "mcpServers": {
        "mochow": {
            "command": "/PATH/TO/uv",
            "args": [
                "--directory",
                "/path/to/mochow-mcp-server-python",
                "run",
                "src/mochow_mcp_server/server.py",
                "--endpoint",
                "http://127.0.0.1:8287",
                "--user",
                "root",
                "--api-key",
                "mochow"
            ]
        }
    }
}

重启 Cursor 或重新加载窗口。

可用工具

百度云向量数据库MCP Server提供以下工具：

除 list_databases、create_database 和 use_database 外，Table、索引、数据和检索操作都需要先调用 use_database 选择目标 Database。

Database操作

• list_databases: 列出数据库中所有的Database

• create_database: 创建一个新的Database

  • 参数：
    • database_name: 待创建的Database名称

• use_database: 切换到一个已存在的Database

  • 参数：
    • database_name: 待切换的Database名称

Table操作

• list_tables: 列出数据库中所有的Table

• create_table: 创建一个新的Table

  • 参数：
    • table_name: Table名称
    • fields: 字段定义列表，支持 field_name、field_type、primary_key、partition_key、not_null、dimension 等结构化字段；主键和分区键字段省略 not_null 时会按非空处理，显式设置 not_null: false 会被拒绝
    • indexes: 可选索引定义列表，支持向量索引、倒排索引、二级索引和过滤索引；倒排索引使用 index_type: INVERTED，兼容 BM25/FULLTEXT 别名，字段类型必须是 TEXT、TEXT_GBK 或 TEXT_GB18030，未指定 analyzer 时默认使用 ENGLISH_ANALYZER
    • replication: 副本数
    • partition_num: 分区数量
    • partition_type: 分区类型
    • enable_dynamic_field: 是否启用动态字段
    • description: Table描述
    • ttl: 数据过期时间，0 表示不启用

• describe_table: 获取指定Table的详细信息

  • 参数：
    • table_name: Table名称

• stats_table: 获取指定Table的统计信息

  • 参数：
    • table_name: Table名称

数据操作

• upsert_rows: 向Table中写入或覆盖数据

  • 参数：
    • table_name: Table名称
    • rows: 待写入的数据行列表
    • vector_fields: 可选向量字段类型映射，例如 {"vector": "FLOAT"}

• update_rows: 使用主键局部更新已有数据

  • 参数：
    • table_name: Table名称
    • updates: 更新操作列表，每项包含 primary_key、可选 partition_key 和 update_fields
    • vector_fields: 可选向量字段类型映射；当 update_fields 中包含向量字段时使用

• query_rows: 使用主键查询数据

  • 参数：
    • table_name: Table名称
    • primary_key: 主键字段和值
    • partition_key: 可选分区键字段和值
    • output_fields: 查询结果中要返回的字段名
    • retrieve_vector: 是否返回向量字段
    • read_consistency: 读一致性，支持 EVENTUAL 和 STRONG

• batch_query_rows: 使用多个主键批量查询数据

  • 参数：
    • table_name: Table名称
    • keys: 主键列表，每项必须包装为 {"primary_key": {"id": "row_1"}}，可包含 partition_key；不要直接传 {"id": "row_1"}
    • output_fields: 查询结果中要返回的字段名
    • retrieve_vector: 是否返回向量字段
    • read_consistency: 读一致性，支持 EVENTUAL 和 STRONG

• delete_table_rows: 使用过滤表达式删除数据

  • 参数：
    • table_name: Table名称
    • filter_expr: 过滤表达式，字符串值必须使用单引号，例如 id = 'row_1'

• delete_rows_by_key: 使用主键删除单行数据

  • 参数：
    • table_name: Table名称
    • primary_key: 主键字段和值
    • partition_key: 可选分区键字段和值

• select_table_rows: 使用过滤表达式查询数据

  • 参数：
    • table_name: Table名称
    • filter_expr: 过滤表达式，字符串值必须使用单引号，例如 id = 'row_1'
    • limit: 查询结果的最大条数
    • output_fields: 查询结果中要返回的字段名
    • read_consistency: 读一致性，支持 EVENTUAL 和 STRONG

索引操作

• create_vector_index: 在指定向量字段上创建向量索引 同一向量字段不要重复创建多个向量索引；验证创建/删除生命周期时，使用未建索引字段或临时表。

  • 参数：

    • table_name: Table名称
    • index_name: 向量索引名称
    • field_name: 向量字段名称
    • index_type: 向量索引类型
    • metric_type: 向量索引的距离度量
    • params: 向量索引的创建参数
    • auto_build: 是否在创建索引后立即触发一次 rebuild_vector_index
    • auto_build_policy: 可选，Mochow 原生自动构建策略；设置后会发送 autoBuildPolicy，支持 TIMING、PERIODICAL、ROW_COUNT_INCREMENT

  • 支持的向量索引类型：

    • FLAT
    • HNSW
    • HNSWPQ
    • HNSWSQ
    • PUCK
    • IVF
    • IVFSQ
    • DISKANN
    • SPARSE_OPTIMIZED_FLAT

• create_scalar_index: 创建标量索引

  • 参数：
    • table_name: Table名称
    • index_name: 索引名称
    • field_name: 单字段索引的字段名；创建 SECONDARY 索引时目标字段必须在建表时设置 not_null: true
    • fields: 多字段过滤索引的字段名列表
    • index_type: 标量索引类型，支持 SECONDARY 和 FILTERING

• rebuild_vector_index: 重新构建指定向量索引

  • 参数：
    • table_name: Table名称
    • index_name: 向量索引名称

• drop_vector_index: 删除指定向量索引

  • 参数：
    • table_name: Table名称
    • index_name: 向量索引名称

• describe_index: 获取指定索引的详情信息

  • 参数：
    • table_name: Table名称
    • index_name: 索引名称

检索操作

• vector_search: 执行带标量过滤的向量相似性检索

  • 参数：
    • table_name: Table名称
    • vector: 向量
    • vector_field: 向量字段名称
    • limit: 相似性检索结果中返回最接近目标向量的记录数量
    • filter_expr: 过滤表达式
    • output_fields: 查询结果中要返回的字段名
    • params: 检索参数，支持 ef、pruning、searchCoarseCount、nprobe、W、searchL、twoPhaseRetrieval 等
    • offset: 结果偏移量
    • vector_type: 向量类型，支持 FLOAT、BINARY 和 SPARSE_FLOAT

• vector_range_search: 执行向量距离范围检索

  • 参数：
    • table_name: Table名称
    • vector: 向量
    • distance_near: 距离范围下界
    • distance_far: 距离范围上界
    • vector_field: 向量字段名称
    • limit: 返回结果数量
    • filter_expr: 过滤表达式
    • output_fields: 查询结果中要返回的字段名
    • params: 检索参数
    • offset: 结果偏移量
    • vector_type: 向量类型

• fulltext_search: 执行全文检索

  • 参数：
    • table_name: Table名称
    • index_name: 倒排索引名称
    • search_text: 全文检索的检索表达式
    • limit: 全文检索返回相关性最高的条目数
    • filter_expr: 过滤表达式
    • output_fields: 查询结果中要返回的字段名

• hybrid_search: 执行向量检索和BM25全文检索融合

  • 参数：
    • table_name: Table名称
    • vector: 向量
    • index_name: 倒排索引名称
    • search_text: 全文检索表达式
    • vector_field: 向量字段名称
    • limit: 返回结果数量
    • filter_expr: 过滤表达式
    • output_fields: 查询结果中要返回的字段名
    • vector_weight: 向量检索权重
    • bm25_weight: BM25检索权重
    • params: 向量检索参数
    • vector_type: 向量类型

环境变量

• MOCHOW_ENDPOINT: 百度云向量数据库连接实例URI
• MOCHOW_USER: 百度云向量数据库实例认证用户，默认值为 root
• MOCHOW_API_KEY: 百度云向量数据库实例API密钥

验证

基础语法检查

uv run python -m compileall src

使用样例

使用Claude Desktop

Example 1: 列出数据库中所有的Database

How many databases do i have in the mochow db?

Claude将使用百度云向量数据库MCP Server提供的list_databases来获取数据库列表.

Let me check how many databases you have in the Mochow instance.

You have 2 databases in your Mochow instance:

1. book
2. test

Example 2: 查看指定表的schema信息

I want to get the detail of table named book_segments in database book.

Claude将使用百度云向量数据库MCP Server提供的describe_table来获取表的详情信息.

I'll help you get the details of the "book_segments" table in the "book" database. Let me first switch to the "book" database and then describe the table.

Here's the information about the "book_segments" table in the "book" database:

Database: book
Table Name: book_segments
Creation Time: 2025-05-06 11:08:22
State: NORMAL

Schema:

id (STRING)
Primary Key: Yes
Partition Key: Yes
Not Null: Yes

bookName (STRING)
Not Null: Yes

author (STRING)
Not Null: No

page (UINT32)
Not Null: No

segment (TEXT)
Not Null: No

vector (FLOAT_VECTOR)
Not Null: Yes
Dimension: 1024

Indexes
book_name_filtering_idx (FILTERING_INDEX)
Field: bookName
Order: ASCEND
Structure Type: DEFAULT

vector_idx (HNSW)
Field: vector
Metric Type: L2
Auto Build: False
Parameters: (M: 16 efConstruction: 200)