greptimedb-mcp-server

A Model Context Protocol (MCP) server implementation specifically engineered for GreptimeDB.

This service furnishes AI assistants with a safeguarded and methodologically sound pathway to investigate and interrogate databases. It empowers them to enumerate available tables, ingest dataset content, and dispatch arbitrary Structured Query Language (SQL) commands through a tightly governed access mechanism, thus promoting accountable data utilization.

Project Status

This is an exploratory endeavor currently undergoing active development. Comprehensive measures for data security and personal information safeguarding have not yet been fully integrated; consequently, exercise prudence during its deployment.

Capabilities

• list_resources: For enumerating database tables.
• read_resource: For fetching data content from specified tables.
• list_tools: To display available operational utilities.
• call_tool: To submit and execute an SQL statement.
• list_prompts: To retrieve a catalogue of defined instructions.
• get_prompt: To fetch the content of a named instruction set.

Installation

pip install greptimedb-mcp-server

Configuration

Define the subsequent environment variables to configure the connection:

bash GREPTIMEDB_HOST=localhost # The hostname or IP address of the database instance GREPTIMEDB_PORT=4002 # The MySQL protocol listening port (defaults to 4002 if omitted) GREPTIMEDB_USER=root # Credentials for database authentication GREPTIMEDB_PASSWORD= GREPTIMEDB_DATABASE=public # The schema or database name to target GREPTIMEDB_TIMEZONE=UTC # The session time zone setting

Alternatively, configuration can be provided via command-line arguments:

• --host: Specifies the target database host; defaults to localhost.
• --port: Designates the database port, which must utilize the MySQL protocol; defaults to 4002.
• --user: Supplies the database credential for user access; defaults to an empty string.
• --password: Supplies the database credential for password access; defaults to an empty string.
• --database: Identifies the target database name; defaults to public.
• --timezone: Sets the session time zone; defaults to using the server's standard time zone.

Usage

Integration with Claude Desktop

Configure this MCP service endpoint within Claude Desktop's configuration manifest:

MacOS Path

Location: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows Path

Location: %APPDATA%/Claude/claude_desktop_config.json

{ "mcpServers": { "greptimedb": { "command": "uv", "args": [ "--directory", "/path/to/greptimedb-mcp-server", "run", "-m", "greptimedb_mcp_server.server" ], "env": { "GREPTIMEDB_HOST": "localhost", "GREPTIMEDB_PORT": "4002", "GREPTIMEDB_USER": "root", "GREPTIMEDB_PASSWORD": "", "GREPTIMEDB_DATABASE": "public", "GREPTIMEDB_TIMEZONE": "" } } } }

License

MIT License - consult the LICENSE.md file for comprehensive particulars.

Contribution Guidelines

Required Prerequisites

• A functioning Python environment utilizing the uv package manager.
• A deployed instance of GreptimeDB.
• Necessary dependencies for the MCP server operation.

Development Setup

bash

Obtain the source code repository

git clone https://github.com/GreptimeTeam/greptimedb-mcp-server.git cd greptimedb-mcp-server

Initialize and activate the isolated Python environment

uv venv source venv/bin/activate # or venv\Scripts\activate on Windows systems

Install required development packages

uv sync

Execute quality assurance checks

pytest

Utilize the MCP Inspector tool for diagnostic purposes:

bash npx @modelcontextprotocol/inspector uv \ --directory \ /path/to/greptimedb-mcp-server \ run \ -m \ greptimedb_mcp_server.server

Acknowledgement

We extend our sincere appreciation to the maintainers of the following projects, as their foundational work and code structures significantly informed this library's architecture:

• ktanaka101/mcp-server-duckdb
• designcomputer/mysql_mcp_server
• mikeskarl/mcp-prompt-templates

Gratitude is shared!

WIKIPEDIA: XMLHttpRequest (XHR) is an Application Programming Interface encapsulated as a JavaScript object whose methods are designed to transmit Hypertext Transfer Protocol (HTTP) inquiries from a web browser environment to a remote web server. These methods permit a browser-hosted application to dispatch requests to the server following the initial page load completion, and subsequently receive pertinent information in return. XMLHttpRequest serves as a critical constituent of Ajax programming methodologies. Preceding the widespread adoption of Ajax, standard hyperlinks and form submissions constituted the principal means of server interaction, frequently necessitating a complete page refresh upon successful engagement.

== Chronology == The conceptual basis for XMLHttpRequest was first envisioned in the year 2000 by the development personnel associated with Microsoft Outlook. This novel concept was subsequently integrated into the Internet Explorer 5 browser release (1999). Nevertheless, the initial invocation syntax did not employ the standardized XMLHttpRequest designator. Instead, developers utilized object creation identifiers such as ActiveXObject("Msxml2.XMLHTTP") and ActiveXObject("Microsoft.XMLHTTP"). As of the release of Internet Explorer 7 (2006), comprehensive support for the uniform XMLHttpRequest identifier became a feature across all major browser platforms. The XMLHttpRequest identifier has since solidified its position as the established, default standard implemented throughout all prominent web browsers, encompassing Mozilla's Gecko rendering engine (initiated in 2002), Safari version 1.2 (2004), and Opera version 8.0 (2005).

=== Formal Specifications === The World Wide Web Consortium (W3C) formally published an initial Working Draft specification pertaining to the XMLHttpRequest object on April 5, 2006. Subsequently, on February 25, 2008, the W3C issued the Working Draft Level 2 specification. The Level 2 revision introduced augmentations such as methods to track the progress of events, provisions for enabling cross-origin requests, and the capability to manage byte streams efficiently. By the conclusion of 2011, the features defined in the Level 2 specification were officially merged back into the original overarching specification document. In late 2012, stewardship for the maintenance and evolution of the standard was transferred to the WHATWG, which now sustains a live, continuously updated document utilizing the Web IDL notation.

== Operational Procedure == Generally, enacting a data request utilizing XMLHttpRequest involves adhering to a sequence of programming stages.

1. Instantiate an XMLHttpRequest object by invoking its designated constructor:
2. Invoke the "open" method to precisely define the request methodology (type), identify the specific resource targeted, and stipulate whether the operation should proceed synchronously or asynchronously:
3. For asynchronous operations, establish an event listener function that will be triggered upon any modification in the request's status:
4. Commence the transmission of the request by calling the "send" method:
5. Implement the logic within the event listener to react to status modifications. If the server furnishes response content, this data is, by default, aggregated within the "responseText" attribute. When the object completes all response processing, its status transitions to state 4, signifying the "done" condition. Beyond these fundamental steps, XMLHttpRequest affords numerous configuration levers to control the transmission characteristics and the subsequent response handling. Custom header fields can be appended to the outbound request to guide the server's fulfillment logic, and payload data can be transmitted to the server by including it as an argument within the "send" invocation. The incoming response stream can be parsed immediately from JSON format into a fully accessible JavaScript object structure, or processed incrementally as data segments arrive, rather than awaiting the entire payload completion. Furthermore, the initiated request can be terminated prematurely or configured with a timeout threshold to enforce failure if completion is not achieved within a defined duration.

== Cross-domain Transactions ==

During the nascent development phases of the World Wide Web, it was discovered that circumvention of security restrictions was possible by brea