QuestDB MCP Server

QuestDB MCP服务器

QuestDB的模型上下文协议（MCP）服务器，使AI助手能够通过查询和插入数据的工具与QuestDB数据库进行交互。

特性

• 查询执行：对具有结构化输出的QuestDB表执行SELECT查询
• 数据插入：使用InfluxDB线路协议将数据插入QuestDB表
• 表格管理：列出表并描述表架构
• 自动模式创建：插入时会自动创建表和列
• 类型安全：通过Zod模式验证完全支持TypeScript
• 结构化输出：所有工具都返回带有输出模式的结构化内容
• MCP日志记录：集成MCP日志消息，以提高可观察性
• 错误处理：全面的错误处理和优雅的降级
• 服务器说明：AI助手的内置服务器指令
• 优雅地关闭：正确清理信号情报/信号机信号

先决条件

• Node.js v16或更新版本
• QuestDB实例正在运行（请参阅 QuestDB快速入门)

安装

作为一个包裹

从npm安装：

npm install questdbmcp

注： 此包在npm上公开可用。安装或使用它不需要身份验证或配置。

来源

1. 克隆此存储库或导航到项目目录：

   cd questdbmcp

1. 安装依赖项：

   npm install

1. 构建项目：

   npm run build

配置

可以使用环境变量配置服务器：

• QUESTDB_HOST -QuestDB主机（默认值： localhost)
• QUESTDB_PORT -QuestDB端口（默认值： 9000)
• QUESTDB_USERNAME -查询数据库用户名（可选，用于身份验证）
• QUESTDB_PASSWORD -查询数据库密码（可选，用于身份验证）
• QUESTDB_AUTO_FLUSH_ROWS -N行后自动冲洗（可选）
• QUESTDB_AUTO_FLUSH_INTERVAL -自动刷新间隔（毫秒）（可选）

用法

此软件包有两种使用方式：

1.CLI用法

直接运行MCP服务器：

npm start

或用于开发：

npm run dev

或全局安装：

npm install -g questdbmcp
questdbmcp

2.图书馆使用

在TypeScript项目中作为依赖项安装：

npm install questdbmcp

基本用法

import { QuestDBMCPServer, loadConfig } from 'questdbmcp';

// Load configuration from environment variables
const config = loadConfig();

// Create server instance
const server = new QuestDBMCPServer(config);

// Start the server
await server.run();

自定义配置

import { QuestDBMCPServer, QuestDBConfig } from 'questdbmcp';

const config: QuestDBConfig = {
  host: 'localhost',
  port: 9000,
  username: 'admin',
  password: 'quest',
};

const server = new QuestDBMCPServer(config, {
  setupProcessHandlers: false, // Don't set up process handlers when using as library
  serverName: 'my-questdb-server',
  serverVersion: '1.0.0',
  instructions: 'Custom server instructions...',
});

await server.run();

使用自定义运输

import { QuestDBMCPServer, QuestDBConfig } from 'questdbmcp';
import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
import express from 'express';

const config: QuestDBConfig = {
  host: 'localhost',
  port: 9000,
};

const server = new QuestDBMCPServer(config, {
  setupProcessHandlers: false,
});

const app = express();
app.use(express.json());

app.post('/mcp', async (req, res) => {
  const transport = new StreamableHTTPServerTransport({
    sessionIdGenerator: undefined,
    enableJsonResponse: true,
  });

  res.on('close', () => {
    transport.close();
  });

  await server.server.connect(transport);
  await transport.handleRequest(req, res, req.body);
});

app.listen(3000, () => {
  console.log('MCP server running on http://localhost:3000/mcp');
});

访问内部组件

import { QuestDBMCPServer } from 'questdbmcp';

const server = new QuestDBMCPServer(config);

// Access the underlying MCP server
const mcpServer = server.server;

// Access the QuestDB client
const client = server.questDBClient;

// Access the logger
const logger = server.log;

// Use the client directly
const tables = await client.listTables();
const result = await client.query('SELECT * FROM my_table LIMIT 10');

// Use the logger
await logger.info('Custom log message', { metadata: 'value' });

创建自定义工具

import { QuestDBMCPServer, QuestDBConfig } from 'questdbmcp';
import { z } from 'zod';

const config: QuestDBConfig = {
  host: 'localhost',
  port: 9000,
};

const server = new QuestDBMCPServer(config, {
  setupProcessHandlers: false,
});

// Access the underlying MCP server to register custom tools
server.server.registerTool(
  'my-custom-tool',
  {
    title: 'My Custom Tool',
    description: 'A custom tool that uses QuestDB',
    inputSchema: {
      param: z.string().describe('A parameter'),
    },
  },
  async ({ param }) => {
    // Use the QuestDB client
    const client = server.questDBClient;
    const result = await client.query(`SELECT * FROM my_table WHERE col = '${param}'`);
    
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify(result, null, 2),
        },
      ],
    };
  }
);

await server.run();

关机

// Gracefully shutdown the server
await server.shutdown();

TypeScript类型

所有类型均已导出并可供使用：

import type {
  QuestDBConfig,
  QueryResult,
  QuestDBMCPServerOptions,
} from 'questdbmcp';

可用工具

1. query

在QuestDB上执行SQL SELECT查询。

参数：

• query （字符串，必填）：要执行的SQL查询（仅限SELECT查询）
• format （字符串，可选）：输出格式- json 或 csv （默认值： json)

例子：

{
  "query": "SELECT * FROM trades LIMIT 10",
  "format": "json"
}

2. insert

将数据插入QuestDB表。如果表和列不存在，则会自动创建它们。

参数：

• table （string，必填）：要插入的表的名称
• data （object，必填）：包含要插入的数据的对象

- 键是列名 - 值是数据（字符串、数字、布尔值） - 使用 timestamp 显式时间戳键（自纪元以来的毫秒数） - 如果 timestamp 未提供，使用当前时间

例子：

{
  "table": "trades",
  "data": {
    "symbol": "ETH-USD",
    "side": "sell",
    "price": 2615.54,
    "amount": 0.00044,
    "timestamp": 1699123456789
  }
}

3. list_tables

列出QuestDB数据库中的所有表。

参数： 无

4. describe_table

获取特定表的架构。

参数：

• table （string，必填）：要描述的表的名称

例子：

{
  "table": "trades"
}

QuestDB设置

Docker快速入门

docker run \
  -p 9000:9000 -p 9009:9009 -p 8812:8812 -p 9003:9003 \
  questdb/questdb:9.1.1

Homebrew快速入门（macOS）

brew install questdb

QuestDB Web控制台将在以下网址提供：http://localhost:9000

发展

建筑

npm run build

类型检查

npm run typecheck

发展模式

npm run dev

数据类型

插入工具会自动将JavaScript类型映射到QuestDB类型：

• 字符串 → SYMBOL （索引字符串类型）
• 数字（整数） → LONG
• 数字（浮点数） → DOUBLE
• 布尔 → BOOLEAN
• 时间戳 → TIMESTAMP （使用时 timestamp 现场）

安全说明

• 只允许通过SELECT查询 query 安全工具
• 服务器使用QuestDB REST API进行查询，使用InfluxDB Line Protocol进行插入
• 如果QuestDB实例需要，则支持通过用户名/密码进行身份验证

例子

插入交易数据

{
  "tool": "insert",
  "arguments": {
    "table": "trades",
    "data": {
      "symbol": "BTC-USD",
      "side": "buy",
      "price": 39269.98,
      "amount": 0.001
    }
  }
}

查询数据

{
  "tool": "query",
  "arguments": {
    "query": "SELECT symbol, price, amount FROM trades WHERE symbol = 'BTC-USD' ORDER BY timestamp DESC LIMIT 10"
  }
}

列表表格

{
  "tool": "list_tables",
  "arguments": {}
}

许可证

麻省理工学院

资源

• QuestDB文档
• 模型上下文协议