Kdb X MCP Server

KDB-X MCP服务器

该服务器使最终用户能够通过自然语言查询KDB-X数据，为无缝数据交互提供生产级资源、提示和工具。

它建立在具有可配置模板的可扩展框架之上，允许根据您的特定需求进行直观的扩展和定制集成。

该服务器利用精心策划的资源、智能提示和强大的工具相结合，为与KDB-X交互的用户和AI模型提供适当的防护和指导。

目录

• 支持的环境
• 先决条件
• 快速入门
• 特性
• KDB-X设置
• MCP服务器安装
• 安全注意事项
• 运输选项
• 命令行工具
• 配置嵌入
• MCP客户端配置
• 提示/资源/工具
• 发展
• 测试
• 故障排除
• 有用的资源

支持的环境

下表显示了支持的操作系统的安装选项：

KDB-X MCP服务器可以连接到一个KDB服务——KDB-X或KDB+，而不是两者都连接。 \ 所选的KDB服务需要侦听KDB-X MCP服务器可访问的主机和端口。

• KDB-X：仅限Mac/Linux/WSL（不支持本机Windows）
• KDB+：Windows/Mac/Linux/WSL
• MCP 服务器：需要UV（Windows/Mac/Linux/WSL）
• 紫外线：运行MCP服务器所需
• NPX：需要使用Claude Desktop进行流式http传输
• 标准运输：仅当您的MCP客户端和MCP服务器位于同一主机上时才有效

有关MCP客户端的详细信息，请参阅 MCP客户端配置

先决条件

在安装和运行KDB-X MCP服务器之前，请确保您已满足以下要求：

• 已克隆此仓库
• A. KDB-X/KDB+ 在MCP服务器可访问的主机和端口上侦听服务

- 参见示例- KDB-X设置 / KDB+设置 - KDB-X可以通过注册来安装 KDB-X公开预览 -看 KDB-X文档 用于支持信息 - Windows用户可以在Windows上运行KDB-X MCP服务器，并通过WSL或在Linux上运行的远程KDB-X数据库连接到本地KDB-X数据 - Windows用户可以通过在上安装KDB-X来运行本地KDB-X数据库 Windows 子系统 for Linux，并使用默认值 可流式传输http 运行时 KDB-X MCP服务器 -两者共享同一个本地主机网络。 - 有关KDB-X使用限制的详细信息，请参阅 文档

• UV已安装 用于运行KDB-X MCP服务器-可在Windows/Mac/Linux/WSL上使用
• 一 MCP客户端 已安装-请参阅 MCP客户端配置
• NPX 需要使用 streamable-http 使用Claude Desktop进行运输

- npx 如果您使用的是其他MCP客户端，则可能不需要-请参阅您选择的MCP客户端的文档 - npx 与捆绑在一起 节点 安装程序-可在Windows/Mac/Linux/WSL上使用 - 看 具有流式http的示例配置

快速入门

要使用空的KDB-X数据库演示KDB-X MCP服务器的基本用法，请按照以下快速入门步骤进行操作。

注意：确保您遵循了必要的 先决条件步骤

1. 打开在端口上侦听的KDB-X服务。

默认情况下，KDB-X MCP服务器将连接到端口5000上的KDB-X服务- 但这是可以改变的 通过命令行标志或环境变量。

> 注意：KDB-X目前在Windows上不受支持-如果您使用的是Windows，我们建议您在WSL上运行KDB-X，如 先决条件步骤

   q -p 5000

1. 加载ai和sql接口。

   .ai:use`kx.ai
   .s.init[]

1. 添加虚拟表，例如。 trade.

   rows:10000;
   trade:([]time:.z.d+asc rows?.z.t;sym:rows?`AAPL`GOOG`MSFT`TSLA`AMZN;price:rows?100f;size:rows?1000);

1. 配置您的MCP客户端 您选择的交通工具。

1. 启动MCP服务器.

如果您已配置 MCP客户端 随着 stdio传输，则不需要此步骤。请转到下一步（您的MCP客户端将为您管理启动MCP服务器）。

   uv run mcp-server

1. 启动MCP客户端，并验证工具、提示和资源部分是否可见。请咨询您的具体信息 MCP客户端配置 对于这些细节。

1. 加载数据库上下文：选择 kdbx_describe_tables 和 kdbx_sql_query_guidance 资源 将它们添加到您的对话中。这将为您的MCP客户端提供数据库结构和可用表的概述，以及编写有效SQL查询的指导。

1. 浏览特定表格：使用 kdbx_table_analysis 提示 获取数据库中各个表的详细分析和见解。

1. 用自然语言提问：使用简明英语与您的KDB-X数据库进行交互。您的MCP客户端将自动使用 kdbx_run_sql_query 工具 根据您的请求执行适当的查询。

特性

• KDB-X的SQL接口：对KDB-X数据库运行SELECT SQL查询
• 内置查询安全保护：自动检测和阻止危险的SQL操作，如INSERT、DROP、DELETE等。
• 智能查询结果优化：智能结果截断（最多1000行），明确传达数据限制信息
• LLM SQL查询指南：全面的LLM就绪MCP资源(file://guidance/kdb-sql-queries)包含语法示例和最佳实践
• 数据库架构发现：使用附带的MCP资源探索和理解您的数据库表和结构，以获得快速、智能的见解。
• 自动发现系统：从各自的目录中自动发现和注册工具、资源和提示
• 弹性连接管理：具有自动重试逻辑和连接缓存的强大KDB-X连接处理
• 现成的扩展模板：现成的工具、资源和提示模板，包含扩展功能的最佳实践和文档
• 统一智能：提示、工具和MCP资源协同工作：智能提示、专用工具和精心策划的MCP资源的强大组合——所有这些共同作用，提供快速、优化和情境感知的结果。
• HTTP流协议支持：支持最新的MCP流式HTTP协议，以实现高效的数据流，同时自动阻止弃用的SSE协议。

KDB-X设置

KDB-X MCP服务器连接到指定主机和端口上的KDB-X服务。

要启动KDB-X服务并使其在本地可访问，您可以运行：

q -p 5000

KDB-X MCP服务器使用其SQL接口与KDB-X服务通信。

加载SQL接口：

.s.init[]

使用KDB-X的AI工具

注意：KDB+用户无法访问相似性搜索工具

启用以下工具

• “kdbx相似性搜索”
• “kdbx_hybrid_search”

使用KDB-X MCP服务器，您需要：

• 奔跑吧 KDB-X 0.1.2或更高版本.
• 通过以下方式在KDB-X会话中加载ai-libs模块：

.ai:use`kx.ai

KDB+设置

KDB-X MCP服务器连接到指定主机和端口上的KDB+服务。

要启动KDB+服务并使其在本地可访问，您可以运行：

q -p 5000

KDB-X MCP服务器使用其SQL接口与KDB+服务通信。

使用KDB+时 s.k\_ 文件必须存在于您的 QHOME -此文件与insights核心捆绑在一起

加载SQL接口：

\l s.k_

MCP服务器安装

MCP服务器可以安装在Windows、Mac、Linux和 Windows 子系统 for Linux

克隆仓库

git clone https://github.com/KxSystems/kdb-x-mcp-server.git
cd kdb-x-mcp-server

运行服务器

服务器将以以下方式启动 streamable-http 默认运输。

对于安装了WSL的Windows用户-使用时 streamable-http MCP服务器可以在Windows或WSL上运行。对于这两种情况，MCP服务器将在同一个共享的本地主机网络上可用。MCP客户端（在Windows上运行）将通过以下方式连接 localhost。因此，此存储库可以克隆到Windows或WSL。 uv 需要安装在运行MCP服务器的同一操作系统上。

如果您正在使用 stdio 在Windows上，您的MCP客户端将管理启动和停止MCP服务器。因此，需要将此存储库克隆到Windows文件系统。 uv 需要在Windows上安装。

uv run mcp-server

运输选项

有关支持的传输的更多信息，请参阅官方文档

• 可流式传输http
• 标准

注意：我们不支持 SSE 传输（服务器发送的事件），因为自2024-11-05协议版本以来，它已被弃用。

安全注意事项

为了简化入门，我们建议在同一内部网络上运行您的MCP客户端、KDB-X MCP服务器和KDB-X数据库。

加密数据库连接

如果您需要KDB-X MCP服务器和KDB-X数据库之间的加密连接，可以使用启用TLS --db.tls=true

这需要使用TLS设置KDB-X数据库作为先决条件：

• 您可以关注 kdb+SSL/TLS指南 使用KDB-X数据库设置TLS
• 如果您使用自签名证书：

- 您需要指定自签名CA证书的位置 - 设置 KX_SSL_CA_CERT_FILE 环境变量指向KDB-X数据库正在使用的CA证书文件 - 或者，您可以通过设置绕过证书验证 KX_SSL_VERIFY_SERVER=NO 用于开发和测试

加密MCP客户端连接

如果您需要MCP客户端和KDB-X MCP服务器之间的加密连接：

• 默认情况下，KDB-X MCP服务器使用可流式传输的http，并在127.0.0.1:8000启动本地主机服务器。我们不建议将其暴露在外部。
• 您可以选择在KDB-X MCP服务器前设置HTTPS代理，例如 使者 或 引擎X 用于HTTPS终止
• 使用stdio传输时，不需要这样做，因为通信是通过同一主机上的标准输入/输出流进行的

注意：对FastMCP v2的身份验证功能进行了评估，但KDB-X MCP服务器将暂时保持在v1上，以保持广泛的模型兼容性，直到客户端/模型赶上，届时我们将进行转换。

命令行工具

uv run mcp-server -h
usage: mcp-server [-h] [--mcp.server-name str] [--mcp.log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}]
                  [--mcp.transport {stdio,streamable-http}] [--mcp.port int] [--mcp.host str] [--db.host str]
                  [--db.port int] [--db.username str] [--db.password SecretStr] [--db.tls bool] [--db.timeout int]
                  [--db.retry int] [--db.embedding-csv-path str] [--db.metric str] [--db.k int]

KDB-X MCP Server that enables interaction with KDB-X using natural language

options:
  -h, --help            show this help message and exit

mcp options:
  MCP server configuration and transport settings

  --mcp.server-name str
                        Name identifier for the MCP server instance [env: KDBX_MCP_SERVER_NAME] (default:
                        KDBX_MCP_Server)
  --mcp.log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}
                        Logging verbosity level [env: KDBX_MCP_LOG_LEVEL] (default: INFO)
  --mcp.transport {stdio,streamable-http}
                        Communication protocol: 'stdio' (pipes) or 'streamable-http' (HTTP server) [env:
                        KDBX_MCP_TRANSPORT] (default: streamable-http)
  --mcp.port int        HTTP server port - ignored when using stdio transport [env: KDBX_MCP_PORT] (default: 8000)
  --mcp.host str        HTTP server bind address - ignored when using stdio transport [env: KDBX_MCP_HOST] (default:
                        127.0.0.1)

db options:
  KDB-X database connection settings

  --db.host str         KDB-X server hostname or IP address [env: KDBX_DB_HOST] (default: 127.0.0.1)
  --db.port int         KDB-X server port number [env: KDBX_DB_PORT] (default: 5000)
  --db.username str     Username for KDB-X authentication [env: KDBX_DB_USERNAME] (default: )
  --db.password SecretStr
                        Password for KDB-X authentication [env: KDBX_DB_PASSWORD] (default: )
  --db.tls bool         Enable TLS for KDB-X connections. When using TLS you will need to set the environment variable
                        `KX_SSL_CA_CERT_FILE` that points to the certificate on your local filesystem that your KDB-X
                        server is using. For local development and testing you can set `KX_SSL_VERIFY_SERVER=NO` to
                        bypass this requirement [env: KDBX_DB_TLS] (default: False)
  --db.timeout int      Timeout in seconds for KDB-X connection attempts [env: KDBX_DB_TIMEOUT] (default: 1)
  --db.retry int        Number of connection retry attempts on failure [env: KDBX_DB_RETRY] (default: 2)
  --db.embedding-csv-path str
                        Path to embeddings csv [env: KDBX_DB_EMBEDDING_CSV_PATH] (default:
                        src/mcp_server/utils/embeddings.csv)
  --db.metric str       Distance metric used for vector similarity search (e.g., CS, L2, IP) [env: KDBX_DB_METRIC]
                        (default: CS)
  --db.k int            Default number of results to return from vector searches [env: KDBX_DB_K] (default: 5)

CLI配置选项

命令行选项分为两大类：

• MCP选项-配置MCP服务器行为和传输设置
• 数据库选项-配置KDB-X数据库连接设置

有关每个选项的详细信息，请参阅 帮助文本

配置方法

配置值按以下优先级顺序解析：

1. 命令行参数 -最高优先级
2. 环境变量 -第二优先
3. .env文件 -第三优先
4. 默认值 -中定义的默认值 settings.py

环境变量

每个命令行选项都有一个相应的环境变量。例如：

• --mcp.port 7001 ↔ KDBX_MCP_PORT=7001
• --db.host localhost ↔ KDBX_DB_HOST=localhost

注： KDBX_DB_* 指向KDB+服务时可以使用环境变量

示例用法

# Using defaults
uv run mcp-server

# Using a .env file
echo "KDBX_MCP_PORT=7001" >> .env
echo "KDBX_DB_RETRY=4" >> .env
uv run mcp-server

# Using environment variables
export KDBX_MCP_PORT=7001
export KDBX_DB_RETRY=4
uv run mcp-server

# Using command line arguments
uv run mcp-server \
    --mcp.port 7001 \
    --db.retry 4

配置嵌入

在启动KDB-X MCP服务器之前，如果要使用相似性搜索，则必须为表配置嵌入模型。 该存储库包括两个即用型嵌入提供程序：OpenAI和SentenceTransformers。 您可以根据需要自定义这些实现，也可以按照下面概述的步骤添加自己的提供者。

1. 更新依赖关系-将所需的嵌入提供程序添加到 pyproject.toml 依赖关系部分。

1. 设置环境变量-如果需要，为所选嵌入提供程序配置所需的API密钥（例如，设置环境变量 OPENAI_API_KEY 使用OpenAI的API）

1. 添加新提供程序-文件 src/mcp_server/utils/embeddings.py 定义基类 EmbeddingProvider 对于所有嵌入提供商。

要添加新的提供程序，请在同一文件中创建一个类，该类扩展了此基类并实现了所有必需的抽象方法。 您可以在同一个文件中使用OpenAI和SentenceTransformers的现有实现作为模板——只需复制和修改它们以满足您的需求。要注册您的提供商，请使用 @register_provider 装饰器位于类定义之上。注册的提供者名称不必跟在提供者的Python包名称后面。

1. 配置表嵌入-更新嵌入配置文件 src/mcp_server/utils/embeddings.csv 使用您的实际数据库和表名，嵌入提供者和模型。您在以下网址提供的名称 embeddings.csv 应与文件中指定的注册提供程序名称匹配 embeddings.py.

MCP客户端配置

KDB-X MCP服务器可与任何兼容MCP的客户端配合使用。

配置指南

• 克劳德桌面版 -macOS和Windows
• -macOS、Linux、Windows和WSL

其他MCP客户端

KDB-X MCP服务器与支持模型上下文协议的任何MCP客户端兼容。有关兼容客户端的完整列表，请参阅 MCP官方客户列表.

提示/资源/工具

提示

analysis_type （可选）：分析选项的类型统计，data_quality sample_size （可选）：数据探索的建议样本量|生成的表分析提示|

资源

工具

query：文本查询转换为矢量和搜索 n （可选）：要返回的结果数|包含搜索结果的词典| |kdbx_hybrid_search |对KDB-X表执行结合向量相似性和稀疏文本搜索的混合搜索| table_name：要搜索的表的名称 query：文本查询，用于转换为密集和稀疏向量进行搜索 n（可选）：要返回的结果数|包含搜索结果的字典|

发展

要添加新工具，请执行以下操作：

1. 在src/mcp_server/tools/中创建一个新的Python文件。
2. 使用_template.py作为参考来实现您的工具。
3. 服务器启动时，该工具将被自动发现并注册。
4. 重新启动MCP客户端以访问新工具。

要添加新资源，请执行以下操作：

1. 在src/mcp_server/resources/中创建一个新的Python文件。
2. 使用_template.py作为引用来实现您的资源。
3. 服务器启动时，将自动发现并注册资源。
4. 重新启动MCP客户端桌面以访问新资源。

要添加新提示，请执行以下操作：

1. 在src/mcp_server/promises/中创建一个新的Python文件。
2. 使用_template.py作为引用来实现您的提示。
3. 服务器启动时，将自动发现并注册提示。
4. 重新启动MCP客户端桌面以访问新提示。

测试

以下工具可以帮助开发、测试和调试新的MCP工具、资源和提示。

• MCP检查员 是Anthropic的交互式开发工具
• 邮递员 创建MCP请求并存储在集合中

故障排除

本节介绍常见的MCP服务器问题。有关特定于客户端的故障排除（配置、连接、工具、提示、资源），请参阅：

• Claude桌面故障排除

导入pykx失败

KDB-X MCP服务器需要有效的KDB-X或KDB+许可证才能运行。

如果您看到类似“导入pykx失败”的错误，请验证以下内容：

• 这 QLIC 环境变量已设置并指向您的许可证目录
• 您的许可证目录包含有效的许可证文件

注意：有效的许可证是指未过期且包含功能标志的许可证 pykx 或 py，以及 embedq 或 eq这些提供了对KDB-X Python（pykx）功能的访问。有关更多信息，请参阅 pykx文档

KDB-X许可证已过期

请更新到最新版本 KDB-X 以获得有效的许可证。

KDB-X连接错误

确保您的KDB-X数据库处于联机状态，并且可以在指定的KDB主机和端口上访问。

默认的KDB-X端点为 localhost:5000，但您可以根据需要通过部分进行更新 命令行工具.

KDB-X SQL接口错误

KDB-X MCP服务器使用其SQL接口与KDB-X服务通信。

如果你收到一个错误，说SQL接口未加载。您可以通过运行.s.init\[\]手动加载它

.s.init[]

MCP服务器端口正在使用中

如果MCP服务器端口正被另一个进程使用，您需要指定一个不同的端口或停止使用该端口的服务。

传输无效

您只能指定 streamable-http 或 stdio.

缺少工具/资源

查看服务器日志中的注册错误。

• 某些工具可能不适用于您的KDB+或KDB-X版本
• 见第节 使用KDB-X的相似性搜索工具 了解更多信息。

与KDB-X数据库交互时出错

确保加载了KDB-X资源，以便您的MCP客户端知道如何与数据库交互。

• kdbx_describe_tables
• kdbx_sql_query_guidance

UV默认路径

有用的资源

• KDB-X文档 有关KDB-X开发的更多一般信息
• KX论坛 社区支持
• KX松弛 寻求支持和反馈