{"id":29563395,"url":"https://github.com/gigapi/gigapi-mcp","last_synced_at":"2025-10-07T07:03:23.870Z","repository":{"id":301231015,"uuid":"1008574037","full_name":"gigapi/gigapi-mcp","owner":"gigapi","description":"MCP Service fopr GigAPI Timeseries Lake","archived":false,"fork":false,"pushed_at":"2025-06-25T20:20:51.000Z","size":93,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-06-25T20:33:10.308Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gigapi.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-25T18:54:29.000Z","updated_at":"2025-06-25T20:20:58.000Z","dependencies_parsed_at":"2025-06-25T20:43:33.146Z","dependency_job_id":null,"html_url":"https://github.com/gigapi/gigapi-mcp","commit_stats":null,"previous_names":["gigapi/gigapi-mcp"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/gigapi/gigapi-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gigapi%2Fgigapi-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gigapi%2Fgigapi-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gigapi%2Fgigapi-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gigapi%2Fgigapi-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gigapi","download_url":"https://codeload.github.com/gigapi/gigapi-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gigapi%2Fgigapi-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278734416,"owners_count":26036404,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-07T02:00:06.786Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-07-18T18:02:02.357Z","updated_at":"2025-10-07T07:03:23.858Z","avatar_url":"https://github.com/gigapi.png","language":"Python","funding_links":[],"categories":["Databases"],"sub_categories":["How to Submit"],"readme":"# \u003cimg src=\"https://github.com/user-attachments/assets/5b0a4a37-ecab-4ca6-b955-1a2bbccad0b4\" /\u003e\n\n# GigAPI MCP Server\n[![PyPI - Version](https://img.shields.io/pypi/v/mcp-gigapi)](https://pypi.org/project/mcp-gigapi)\n[![CodeQL](https://github.com/gigapi/gigapi-mcp/actions/workflows/github-code-scanning/codeql/badge.svg)](https://github.com/gigapi/gigapi-mcp/actions/workflows/github-code-scanning/codeql)\n\nAn MCP server for GigAPI Timeseries Lake that provides seamless integration with Claude Desktop and other MCP-compatible clients.\n\n## Features\n\n### GigAPI Tools\n\n* `run_select_query`  \n   * Execute SQL queries on your GigAPI cluster.  \n   * Input: `sql` (string): The SQL query to execute, `database` (string): The database to execute against.\n   * All queries are executed safely through GigAPI's HTTP API with NDJSON format.\n* `list_databases`  \n   * List all databases on your GigAPI cluster.\n   * Input: `database` (string): The database to use for the SHOW DATABASES query (defaults to \"mydb\").\n* `list_tables`  \n   * List all tables in a database.  \n   * Input: `database` (string): The name of the database.\n* `get_table_schema`  \n   * Get schema information for a specific table.\n   * Input: `database` (string): The name of the database, `table` (string): The name of the table.\n* `write_data`  \n   * Write data using InfluxDB Line Protocol format.\n   * Input: `database` (string): The database to write to, `data` (string): Data in InfluxDB Line Protocol format.\n* `health_check`  \n   * Check the health status of the GigAPI server.\n* `ping`  \n   * Ping the GigAPI server to check connectivity.\n\n## Quick Start\n\n### 1. Install the MCP Server\n\n#### Option A: From PyPI (Recommended)\n```bash\n# The package will be available on PyPI after the first release\n# Users can install it directly with uv\nuv run --with mcp-gigapi --python 3.11 mcp-gigapi --help\n```\n\n#### Option B: From Source\n```bash\n# Clone the repository\ngit clone https://github.com/gigapi/mcp-gigapi.git\ncd mcp-gigapi\n\n# Install dependencies\nuv sync\n```\n\n### 2. Configure Claude Desktop\n\n1. Open the Claude Desktop configuration file located at:  \n   * On macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`  \n   * On Windows: `%APPDATA%/Claude/claude_desktop_config.json`\n2. Add the following configuration:\n\n#### For the Public Demo (Recommended for Testing)\n\n```json\n{\n  \"mcpServers\": {\n    \"mcp-gigapi\": {\n      \"command\": \"uv\",\n      \"args\": [\n        \"run\",\n        \"--with\",\n        \"mcp-gigapi\",\n        \"--python\",\n        \"3.13\",\n        \"mcp-gigapi\"\n      ],\n      \"env\": {\n        \"GIGAPI_HOST\": \"gigapi.fly.dev\",\n        \"GIGAPI_PORT\": \"443\",\n        \"GIGAPI_TIMEOUT\": \"30\",\n        \"GIGAPI_VERIFY_SSL\": \"true\",\n        \"GIGAPI_DEFAULT_DATABASE\": \"mydb\"\n      }\n    }\n  }\n}\n```\n\n#### For Local Development\n\n```json\n{\n  \"mcpServers\": {\n    \"mcp-gigapi\": {\n      \"command\": \"uv\",\n      \"args\": [\n        \"run\",\n        \"--with\",\n        \"mcp-gigapi\",\n        \"--python\",\n        \"3.13\",\n        \"mcp-gigapi\"\n      ],\n      \"env\": {\n        \"GIGAPI_HOST\": \"localhost\",\n        \"GIGAPI_PORT\": \"7971\",\n        \"GIGAPI_TIMEOUT\": \"30\",\n        \"GIGAPI_VERIFY_SSL\": \"false\",\n        \"GIGAPI_DEFAULT_DATABASE\": \"mydb\"\n      }\n    }\n  }\n}\n```\n\n#### With Authentication\n\n```json\n{\n  \"mcpServers\": {\n    \"mcp-gigapi\": {\n      \"command\": \"uv\",\n      \"args\": [\n        \"run\",\n        \"--with\",\n        \"mcp-gigapi\",\n        \"--python\",\n        \"3.13\",\n        \"mcp-gigapi\"\n      ],\n      \"env\": {\n        \"GIGAPI_HOST\": \"your-gigapi-server\",\n        \"GIGAPI_PORT\": \"7971\",\n        \"GIGAPI_USERNAME\": \"your_username\",\n        \"GIGAPI_PASSWORD\": \"your_password\",\n        \"GIGAPI_TIMEOUT\": \"30\",\n        \"GIGAPI_VERIFY_SSL\": \"true\",\n        \"GIGAPI_DEFAULT_DATABASE\": \"your_database\"\n      }\n    }\n  }\n}\n```\n\n3. **Important**: Replace the `uv` command with the absolute path to your `uv` executable:\n   ```bash\n   which uv  # Find the path\n   ```\n4. Restart Claude Desktop to apply the changes.\n\n## API Compatibility\n\nThis MCP server is designed to work with GigAPI's HTTP API endpoints:\n\n### Query Endpoints\n- `POST /query?db={database}\u0026format=ndjson` - Execute SQL queries with NDJSON response format\n- All queries return NDJSON (Newline Delimited JSON) format for efficient streaming\n\n### Write Endpoints\n- `POST /write?db={database}` - Write data using InfluxDB Line Protocol\n\n### Administrative Endpoints\n- `GET /health` - Health check\n- `GET /ping` - Simple ping\n\n## Example Usage\n\n### Writing Data\nUse InfluxDB Line Protocol format:\n\n```bash\ncurl -X POST \"http://localhost:7971/write?db=mydb\" --data-binary @/dev/stdin \u003c\u003c EOF\nweather,location=us-midwest,season=summer temperature=82\nweather,location=us-east,season=summer temperature=80\nweather,location=us-west,season=summer temperature=99\nEOF\n```\n\n### Reading Data\nExecute SQL queries via JSON POST with NDJSON format:\n\n```bash\ncurl -X POST \"http://localhost:7971/query?db=mydb\u0026format=ndjson\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"query\": \"SELECT time, temperature FROM weather WHERE time \u003e= epoch_ns('\\''2025-04-24T00:00:00'\\''::TIMESTAMP)\"}'\n```\n\n### Show Databases/Tables\n```bash\n# Show databases\ncurl -X POST \"http://localhost:7971/query?db=mydb\u0026format=ndjson\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"query\": \"SHOW DATABASES\"}'\n\n# Show tables  \ncurl -X POST \"http://localhost:7971/query?db=mydb\u0026format=ndjson\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"query\": \"SHOW TABLES\"}'\n\n# Count records\ncurl -X POST \"http://localhost:7971/query?db=mydb\u0026format=ndjson\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"query\": \"SELECT count(*), avg(temperature) FROM weather\"}'\n```\n\n## Environment Variables\n\n### Required Variables\n\n* `GIGAPI_HOST`: The hostname of your GigAPI server\n* `GIGAPI_PORT`: The port number of your GigAPI server (default: 7971)\n\n### Optional Variables\n\n* `GIGAPI_USERNAME` or `GIGAPI_USER`: The username for authentication (if required)\n* `GIGAPI_PASSWORD` or `GIGAPI_PASS`: The password for authentication (if required)\n* `GIGAPI_TIMEOUT`: Request timeout in seconds (default: 30)\n* `GIGAPI_VERIFY_SSL`: Enable/disable SSL certificate verification (default: true)\n* `GIGAPI_DEFAULT_DATABASE`: Default database to use for queries (default: mydb)\n* `GIGAPI_MCP_SERVER_TRANSPORT`: Sets the transport method for the MCP server (default: stdio)\n* `GIGAPI_ENABLED`: Enable/disable GigAPI functionality (default: true)\n\n### Example Configurations\n\n#### For Local Development\n```bash\n# Required variables\nGIGAPI_HOST=localhost\nGIGAPI_PORT=7971\n\n# Optional: Override defaults for local development\nGIGAPI_VERIFY_SSL=false\nGIGAPI_TIMEOUT=60\nGIGAPI_DEFAULT_DATABASE=mydb\n```\n\n#### For Production with Authentication\n```bash\n# Required variables\nGIGAPI_HOST=your-gigapi-server\nGIGAPI_PORT=7971\nGIGAPI_USERNAME=your_username\nGIGAPI_PASSWORD=your_password\n\n# Optional: Production settings\nGIGAPI_VERIFY_SSL=true\nGIGAPI_TIMEOUT=30\nGIGAPI_DEFAULT_DATABASE=your_database\n```\n\n#### For Public Demo\n```bash\nGIGAPI_HOST=gigapi.fly.dev\nGIGAPI_PORT=443\nGIGAPI_VERIFY_SSL=true\nGIGAPI_DEFAULT_DATABASE=mydb\n```\n\n## Data Format\n\nGigAPI uses Hive partitioning with the structure:\n```\n/data\n  /mydb\n    /weather\n      /date=2025-04-10\n        /hour=14\n          *.parquet\n          metadata.json\n```\n\n## Development\n\n### Setup Development Environment\n\n1. Install dependencies:\n   ```bash\n   uv sync --all-extras --dev\n   source .venv/bin/activate\n   ```\n\n2. Create a `.env` file in the root of the repository:\n   ```bash\n   GIGAPI_HOST=localhost\n   GIGAPI_PORT=7971\n   GIGAPI_USERNAME=your_username\n   GIGAPI_PASSWORD=your_password\n   GIGAPI_TIMEOUT=30\n   GIGAPI_VERIFY_SSL=false\n   GIGAPI_DEFAULT_DATABASE=mydb\n   ```\n\n3. For testing with the MCP Inspector:\n   ```bash\n   fastmcp dev mcp_gigapi/mcp_server.py\n   ```\n\n### Running Tests\n\n```bash\n# Run all tests\nuv run pytest -v\n\n# Run only unit tests\nuv run pytest -v -m \"not integration\"\n\n# Run only integration tests\nuv run pytest -v -m \"integration\"\n\n# Run linting\nuv run ruff check .\n\n# Test with public demo\npython test_demo.py\n```\n\n### Testing with Public Demo\n\nThe repository includes a test script that validates the MCP server against the public GigAPI demo:\n\n```bash\npython test_demo.py\n```\n\nThis will test:\n- ✅ Health check and connectivity\n- ✅ Database listing (SHOW DATABASES)\n- ✅ Table listing (SHOW TABLES)\n- ✅ Data queries (SELECT count(*) FROM table)\n- ✅ Sample data retrieval\n\n## PyPI Publishing\n\nThis package is automatically published to PyPI on each GitHub release. The publishing process is handled by GitHub Actions workflows:\n\n- **CI Workflow** (`.github/workflows/ci.yml`): Runs tests on pull requests and pushes to main\n- **Publish Workflow** (`.github/workflows/publish.yml`): Publishes to PyPI when a release is created\n\n### For Users\n\nOnce published, users can install the package directly from PyPI:\n\n```bash\n# Install and run the MCP server\nuv run --with mcp-gigapi --python 3.11 mcp-gigapi\n```\n\n### For Maintainers\n\nTo publish a new version:\n\n1. Update the version in `pyproject.toml`\n2. Create a GitHub release\n3. The workflow will automatically publish to PyPI\n\nSee [RELEASING.md](RELEASING.md) for detailed release instructions.\n\n## Troubleshooting\n\n### Common Issues\n\n1. **Connection refused**: Check that GigAPI is running and the host/port are correct\n2. **Authentication failed**: Verify username/password are correct\n3. **SSL certificate errors**: Set `GIGAPI_VERIFY_SSL=false` for self-signed certificates\n4. **No databases found**: Ensure you're using the correct default database (usually \"mydb\")\n\n### Debug Mode\n\nEnable debug logging by setting the log level:\n\n```python\nimport logging\nlogging.basicConfig(level=logging.DEBUG)\n```\n\n## License\n\nApache-2.0 license\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests\n5. Submit a pull request\n\n## Support\n\n- Issues: [GitHub Issues](https://github.com/gigapi/mcp-gigapi/issues)\n- Documentation: [GigAPI Documentation](https://gigapi.com/docs)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgigapi%2Fgigapi-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgigapi%2Fgigapi-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgigapi%2Fgigapi-mcp/lists"}