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.

Quick Start

1. Install the MCP Server

Option A: From PyPI (Recommended)

# The package will be available on PyPI after the first release
# Users can install it directly with uv
uv run --with mcp-gigapi --python 3.11 mcp-gigapi --help

Option B: From Source

# Clone the repository
git clone https://github.com/gigapi/mcp-gigapi.git
cd mcp-gigapi

# Install dependencies
uv sync

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)

{
  "mcpServers": {
    "mcp-gigapi": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp-gigapi",
        "--python",
        "3.13",
        "mcp-gigapi"
      ],
      "env": {
        "GIGAPI_HOST": "gigapi.fly.dev",
        "GIGAPI_PORT": "443",
        "GIGAPI_TIMEOUT": "30",
        "GIGAPI_VERIFY_SSL": "true",
        "GIGAPI_DEFAULT_DATABASE": "mydb"
      }
    }
  }
}

For Local Development

{
  "mcpServers": {
    "mcp-gigapi": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp-gigapi",
        "--python",
        "3.13",
        "mcp-gigapi"
      ],
      "env": {
        "GIGAPI_HOST": "localhost",
        "GIGAPI_PORT": "7971",
        "GIGAPI_TIMEOUT": "30",
        "GIGAPI_VERIFY_SSL": "false",
        "GIGAPI_DEFAULT_DATABASE": "mydb"
      }
    }
  }
}

With Authentication

{
  "mcpServers": {
    "mcp-gigapi": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp-gigapi",
        "--python",
        "3.13",
        "mcp-gigapi"
      ],
      "env": {
        "GIGAPI_HOST": "your-gigapi-server",
        "GIGAPI_PORT": "7971",
        "GIGAPI_USERNAME": "your_username",
        "GIGAPI_PASSWORD": "your_password",
        "GIGAPI_TIMEOUT": "30",
        "GIGAPI_VERIFY_SSL": "true",
        "GIGAPI_DEFAULT_DATABASE": "your_database"
      }
    }
  }
}

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:

curl -X POST "http://localhost:7971/write?db=mydb" --data-binary @/dev/stdin << EOF
weather,location=us-midwest,season=summer temperature=82
weather,location=us-east,season=summer temperature=80
weather,location=us-west,season=summer temperature=99
EOF

Reading Data

Execute SQL queries via JSON POST with NDJSON format:

curl -X POST "http://localhost:7971/query?db=mydb&format=ndjson" \
  -H "Content-Type: application/json" \
  -d '{"query": "SELECT time, temperature FROM weather WHERE time >= epoch_ns('\''2025-04-24T00:00:00'\''::TIMESTAMP)"}'

Show Databases/Tables

# Show databases
curl -X POST "http://localhost:7971/query?db=mydb&format=ndjson" \
  -H "Content-Type: application/json" \
  -d '{"query": "SHOW DATABASES"}'

# Show tables  
curl -X POST "http://localhost:7971/query?db=mydb&format=ndjson" \
  -H "Content-Type: application/json" \
  -d '{"query": "SHOW TABLES"}'

# Count records
curl -X POST "http://localhost:7971/query?db=mydb&format=ndjson" \
  -H "Content-Type: application/json" \
  -d '{"query": "SELECT count(*), avg(temperature) FROM weather"}'

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

# Required variables
GIGAPI_HOST=localhost
GIGAPI_PORT=7971

# Optional: Override defaults for local development
GIGAPI_VERIFY_SSL=false
GIGAPI_TIMEOUT=60
GIGAPI_DEFAULT_DATABASE=mydb

For Production with Authentication

# Required variables
GIGAPI_HOST=your-gigapi-server
GIGAPI_PORT=7971
GIGAPI_USERNAME=your_username
GIGAPI_PASSWORD=your_password

# Optional: Production settings
GIGAPI_VERIFY_SSL=true
GIGAPI_TIMEOUT=30
GIGAPI_DEFAULT_DATABASE=your_database

For Public Demo

GIGAPI_HOST=gigapi.fly.dev
GIGAPI_PORT=443
GIGAPI_VERIFY_SSL=true
GIGAPI_DEFAULT_DATABASE=mydb

Data Format

GigAPI uses Hive partitioning with the structure:

/data
  /mydb
    /weather
      /date=2025-04-10
        /hour=14
          *.parquet
          metadata.json

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

# Run all tests
uv run pytest -v

# Run only unit tests
uv run pytest -v -m "not integration"

# Run only integration tests
uv run pytest -v -m "integration"

# Run linting
uv run ruff check .

# Test with public demo
python test_demo.py

Testing with Public Demo

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

python test_demo.py

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:

# Install and run the MCP server
uv run --with mcp-gigapi --python 3.11 mcp-gigapi

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:

import logging
logging.basicConfig(level=logging.DEBUG)

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