A Model Context Protocol (MCP) server for QuestDB that enables AI assistants to interact with QuestDB databases through tools for querying and inserting data.
Features
Query Execution: Execute SELECT queries on QuestDB tables with structured output
: Insert data into QuestDB tables using the InfluxDB Line Protocol
Note: This package is publicly available on npm. No authentication or configuration is required to install or use it.
From Source
Clone this repository or navigate to the project directory:
cd questdbmcp
Install dependencies:
npm install
Build the project:
npm run build
Configuration
The server can be configured using environment variables:
QUESTDB_HOST - QuestDB host (default: localhost)
QUESTDB_PORT - QuestDB port (default: 9000)
QUESTDB_USERNAME - QuestDB username (optional, for authentication)
QUESTDB_PASSWORD - QuestDB password (optional, for authentication)
QUESTDB_AUTO_FLUSH_ROWS - Auto-flush after N rows (optional)
QUESTDB_AUTO_FLUSH_INTERVAL - Auto-flush interval in milliseconds (optional)
Usage
This package can be used in two ways:
1. CLI Usage
Run the MCP server directly:
npm start
Or for development:
npm run dev
Or install globally:
npm install -g questdbmcp
questdbmcp
2. Library Usage
Install as a dependency in your TypeScript project:
npm install questdbmcp
Basic Usage
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();
Custom Configuration
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();
Using with Custom Transport
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');
});
Accessing Internal Components
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' });
Creating Custom Tools
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();
Shutdown
// Gracefully shutdown the server
await server.shutdown();
TypeScript Types
All types are exported and available for use:
import type {
QuestDBConfig,
QueryResult,
QuestDBMCPServerOptions,
} from 'questdbmcp';
Available Tools
1. query
Execute a SQL SELECT query on QuestDB.
Parameters:
query (string, required): The SQL query to execute (SELECT queries only)
format (string, optional): Output format - json or csv (default: json)