GigAPI MCP Server

An MCP server for GigAPI Timeseries Lake that provides seamless integration with Claude Desktop and other MCP-compatible clients.

Features

GigAPI Tools

• run_select_query

  • Execute SQL queries on your GigAPI cluster.

  • Input: sql (string): The SQL query to execute, database (string): The database to execute against.

  • All queries are executed safely through GigAPI's HTTP API with NDJSON format.

• list_databases

  • List all databases on your GigAPI cluster.

  • Input: database (string): The database to use for the SHOW DATABASES query (defaults to "mydb").

• list_tables

  • List all tables in a database.

  • Input: database (string): The name of the database.

• get_table_schema

  • Get schema information for a specific table.

  • Input: database (string): The name of the database, table (string): The name of the table.

• write_data

  • Write data using InfluxDB Line Protocol format.

  • Input: database (string): The database to write to, data (string): Data in InfluxDB Line Protocol format.

• health_check

  • Check the health status of the GigAPI server.

• ping

  • Ping the GigAPI server to check connectivity.

Related MCP server: FreeAgent MCP Server

Quick Start

1. Install the MCP Server

Option A: From PyPI (Recommended)

Option B: From Source

2. Configure Claude Desktop

1. Open the Claude Desktop configuration file located at:

   • On macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

   • On Windows: %APPDATA%/Claude/claude_desktop_config.json

2. Add the following configuration:

For the Public Demo (Recommended for Testing)

For Local Development

With Authentication

3. Important: Replace the uv command with the absolute path to your uv executable:

   which uv # Find the path

4. Restart Claude Desktop to apply the changes.

API Compatibility

This MCP server is designed to work with GigAPI's HTTP API endpoints:

Query Endpoints

• POST /query?db={database}&format=ndjson - Execute SQL queries with NDJSON response format

• All queries return NDJSON (Newline Delimited JSON) format for efficient streaming

Write Endpoints

• POST /write?db={database} - Write data using InfluxDB Line Protocol

Administrative Endpoints

• GET /health - Health check

• GET /ping - Simple ping

Example Usage

Writing Data

Use InfluxDB Line Protocol format:

Reading Data

Execute SQL queries via JSON POST with NDJSON format:

Show Databases/Tables

Environment Variables

Required Variables

• GIGAPI_HOST: The hostname of your GigAPI server

• GIGAPI_PORT: The port number of your GigAPI server (default: 7971)

Optional Variables

• GIGAPI_USERNAME or GIGAPI_USER: The username for authentication (if required)

• GIGAPI_PASSWORD or GIGAPI_PASS: The password for authentication (if required)

• GIGAPI_TIMEOUT: Request timeout in seconds (default: 30)

• GIGAPI_VERIFY_SSL: Enable/disable SSL certificate verification (default: true)

• GIGAPI_DEFAULT_DATABASE: Default database to use for queries (default: mydb)

• GIGAPI_MCP_SERVER_TRANSPORT: Sets the transport method for the MCP server (default: stdio)

• GIGAPI_ENABLED: Enable/disable GigAPI functionality (default: true)

Example Configurations

For Local Development

For Production with Authentication

For Public Demo

Data Format

GigAPI uses Hive partitioning with the structure:

Development

Setup Development Environment

1. Install dependencies:

   uv sync --all-extras --dev source .venv/bin/activate

2. Create a .env file in the root of the repository:

   GIGAPI_HOST=localhost GIGAPI_PORT=7971 GIGAPI_USERNAME=your_username GIGAPI_PASSWORD=your_password GIGAPI_TIMEOUT=30 GIGAPI_VERIFY_SSL=false GIGAPI_DEFAULT_DATABASE=mydb

3. For testing with the MCP Inspector:

   fastmcp dev mcp_gigapi/mcp_server.py

Running Tests

Testing with Public Demo

The repository includes a test script that validates the MCP server against the public GigAPI demo:

This will test:

• ✅ Health check and connectivity

• ✅ Database listing (SHOW DATABASES)

• ✅ Table listing (SHOW TABLES)

• ✅ Data queries (SELECT count(*) FROM table)

• ✅ Sample data retrieval

PyPI Publishing

This package is automatically published to PyPI on each GitHub release. The publishing process is handled by GitHub Actions workflows:

• CI Workflow (.github/workflows/ci.yml): Runs tests on pull requests and pushes to main

• Publish Workflow (.github/workflows/publish.yml): Publishes to PyPI when a release is created

For Users

Once published, users can install the package directly from PyPI:

For Maintainers

To publish a new version:

1. Update the version in pyproject.toml

2. Create a GitHub release

3. The workflow will automatically publish to PyPI

See RELEASING.md for detailed release instructions.

Troubleshooting

Common Issues

1. Connection refused: Check that GigAPI is running and the host/port are correct

2. Authentication failed: Verify username/password are correct

3. SSL certificate errors: Set GIGAPI_VERIFY_SSL=false for self-signed certificates

4. No databases found: Ensure you're using the correct default database (usually "mydb")

Debug Mode

Enable debug logging by setting the log level:

License

Apache-2.0 license

Contributing

1. Fork the repository

2. Create a feature branch

3. Make your changes

4. Add tests

5. Submit a pull request

Support

• Issues: GitHub Issues

• Documentation: GigAPI Documentation