{"id":27157143,"url":"https://github.com/johnib/kusto-mcp","last_synced_at":"2025-04-08T20:53:46.200Z","repository":{"id":285559655,"uuid":"958558099","full_name":"johnib/kusto-mcp","owner":"johnib","description":null,"archived":false,"fork":false,"pushed_at":"2025-04-01T12:42:52.000Z","size":0,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-01T12:44:56.430Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/johnib.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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}},"created_at":"2025-04-01T11:51:16.000Z","updated_at":"2025-04-01T12:42:56.000Z","dependencies_parsed_at":"2025-04-01T12:45:02.367Z","dependency_job_id":"275bc35c-92fd-4eda-b11f-ecb22f8dc8fd","html_url":"https://github.com/johnib/kusto-mcp","commit_stats":null,"previous_names":["johnib/kusto-mcp"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johnib%2Fkusto-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johnib%2Fkusto-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johnib%2Fkusto-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johnib%2Fkusto-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/johnib","download_url":"https://codeload.github.com/johnib/kusto-mcp/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247927287,"owners_count":21019506,"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","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-04-08T20:53:45.644Z","updated_at":"2025-04-08T20:53:46.193Z","avatar_url":"https://github.com/johnib.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Kusto MCP Server\n\nA TypeScript implementation of a Model Context Protocol (MCP) server for Azure Data Explorer (Kusto), enabling AI assistants to interact with Kusto databases through a standardized protocol.\n\n## Features\n\n- **Azure Authentication**: Supports Azure CLI and Azure Identity authentication methods\n- **Kusto Operations**:\n  - Initialize connection to ADX clusters\n  - List tables in databases\n  - Show table schemas\n  - List functions in databases\n  - Get code for functions\n  - Execute KQL queries\n- **Schema Caching**: Caches table schemas to reduce redundant calls\n- **Telemetry**: OpenTelemetry integration for activity tracking\n- **Error Handling**: Comprehensive error handling with detailed exceptions\n- **Type Safety**: Full TypeScript type definitions\n- **AI Assistant Guidance**: Detailed description for AI assistants on how to effectively interact with users when working with Azure Data Explorer\n\n## Prerequisites\n\n- Node.js 16.x or higher\n- npm 8.x or higher\n- Access to an Azure Data Explorer (Kusto) cluster\n- Azure CLI or Azure Identity for authentication\n\n## Installation\n\n1. Clone the repository:\n   ```bash\n   git clone https://github.com/yourusername/kusto-mcp.git\n   cd kusto-mcp\n   ```\n\n2. Install dependencies:\n   ```bash\n   npm install\n   ```\n\n3. Build the project:\n   ```bash\n   npm run build\n   ```\n\n## Configuration\n\nCreate a `.env` file based on the provided `.env.example`:\n\n```bash\n# Kusto Configuration\nKUSTO_AUTH_METHOD=azure-cli  # Options: azure-identity, azure-cli\nKUSTO_QUERY_TIMEOUT=60000  # Timeout in milliseconds (default: 60000)\n\n# OpenTelemetry Configuration (optional)\nOTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317/v1/traces\n```\n\n### CLINE MCP configuration\n\nAdd this JSON to the `cline_mcp_settings.json` file:\n\n```JSON\n{\n  \"mcpServers\": {\n    \"kusto-mcp\": {\n      \"command\": \"node\",\n      \"args\": [\n        \"\u003cpath to repo\u003e/kusto-mcp/dist/index.js\"\n      ],\n      \"env\": {},\n      \"disabled\": false,\n      \"autoApprove\": [\n        \"initialize-connection\",\n        \"show-tables\",\n        \"show-table\",\n        \"execute-query\"\n      ]\n    }\n  }\n}\n```\n\n### Visual Studio Code Insiders configuration\n\nAdd this JSON stanza to the `settings.json` file:\n\n```JSON\n    \"mcp\": {\n        \"servers\": {\n            \"kusto-mcp\": {\n                \"type\": \"stdio\",\n                \"command\": \"npm\",\n                \"args\": [\n                    \"--prefix\",\n                    \"\u003cpath to the kusto-mcp source directory\u003e\",\n                    \"run\",\n                    \"start\",\n                    \"--silent\"\n                ]\n            }\n        }\n    },\n\n## Usage\n\n### Running the Server\n\nStart the server:\n\n```bash\nnpm start\n```\n\nFor development with auto-restart:\n\n```bash\nnpm run dev\n```\n\n### MCP Tools\n\nThe server provides the following MCP tools:\n\n1. **initialize-connection**\n   - Creates a connection to an ADX cluster\n   - Parameters:\n     - `cluster_url`: The URL of the Kusto cluster\n     - `database`: The database to connect to\n\n2. **show-tables**\n   - Lists tables in the given database\n\n3. **show-table**\n   - Shows the table schema columns\n   - Parameters:\n     - `tableName`: The name of the table to get the schema for\n\n4. **execute-query**\n   - Runs KQL queries and returns results\n   - Parameters:\n     - `query`: The query to execute\n\n5. **show-functions**\n   - Lists all functions in the given database\n\n6. **show-function**\n   - Provides detailed information on a given function, including its source code\n   - Parameters:\n     - `functionName`: The name of the function to get informationabout\n\n### AI Assistant Guidance\n\nThis MCP server includes detailed guidance for AI assistants on how to effectively interact with users when working with Azure Data Explorer. The guidance includes:\n\n- **Workflow Guidance**: Step-by-step instructions for connection setup, database exploration, query execution, best practices, and query optimization\n- **Conversation Flow**: Suggestions for how to guide users through the interaction, from initial connection to executing analytical queries\n- **Error Handling**: Common error scenarios and how to address them\n- **ADX KQL Specifics**: Best practices for writing efficient KQL queries\n\nThis guidance helps ensure that AI assistants can provide a consistent, helpful experience when helping users interact with Azure Data Explorer through this MCP server.\n\n## Authentication\n\n### Azure Identity Authentication\n\nThe server uses Azure Identity authentication by default.\n\n### Azure CLI Authentication\n\nTo use Azure CLI authentication:\n\n1. Set `KUSTO_AUTH_METHOD=azure-cli` in your `.env` file\n2. Ensure you're logged in with Azure CLI (`az login`)\n\n## Development\n\n### Project Structure\n\n```\nkusto-mcp/\n├── src/\n│   ├── index.ts           # Entry point\n│   ├── server.ts          # MCP server implementation\n│   ├── auth/              # Authentication handlers\n│   │   └── token-credentials.ts\n│   ├── common/            # Common utilities\n│   │   ├── errors.ts      # Error handling\n│   │   └── utils.ts       # Utility functions\n│   ├── operations/        # Kusto operations\n│   │   └── kusto/\n│   │       ├── connection.ts\n│   │       ├── tables.ts\n│   │       ├── queries.ts\n│   │       └── index.ts\n│   └── types/             # TypeScript type definitions\n│       ├── config.ts\n│       └── kusto-interfaces.ts\n├── dist/                  # Compiled JavaScript\n├── .env.example           # Example environment variables\n├── package.json           # Project manifest\n└── tsconfig.json          # TypeScript configuration\n```\n\n### Adding New Operations\n\nTo add a new Kusto operation:\n\n1. Create a new file in `src/operations/kusto/` or extend an existing one\n2. Define the operation function\n3. Export the function from `src/operations/kusto/index.ts`\n4. Add the tool to the server in `src/server.ts`\n\n## Implementation Notes\n\nThis TypeScript implementation mirrors the functionality of the C# version while using the appropriate Node.js libraries:\n\n- Uses `azure-kusto-data` and `azure-kusto-ingest` packages for Kusto operations\n- Implements Azure CLI authentication using `KustoConnectionStringBuilder.withAzLoginIdentity`\n- Provides comprehensive error handling with detailed exceptions\n- Includes OpenTelemetry integration for activity tracking\n- Implements schema caching to reduce redundant calls\n- Uses TypeScript for type safety and better developer experience\n\n## License\n\n[MIT](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjohnib%2Fkusto-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjohnib%2Fkusto-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjohnib%2Fkusto-mcp/lists"}