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

• 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.

# 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

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

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:

{ "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" } } } }

{ "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" } } } }

{ "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.

This MCP server is designed to work with GigAPI's HTTP API 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

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

• GET /health - Health check
• GET /ping - Simple ping

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

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 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"}'

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

• 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)

# 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

# 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

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

GigAPI uses Hive partitioning with the structure:

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

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

# 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

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

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

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

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.

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")

Enable debug logging by setting the log level:

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

Apache-2.0 license

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

• Issues: GitHub Issues
• Documentation: GigAPI Documentation