Microsoft Fabric의 Azure Data Explorer/Eventhouse를 위한 MCP( Model Context Protocol ) 서버입니다.
이를 통해 표준화된 MCP 인터페이스를 통해 Azure Data Explorer/Eventhouse 클러스터 및 데이터베이스에 액세스할 수 있으므로 AI 도우미가 KQL 쿼리를 실행하고 데이터를 탐색할 수 있습니다.
[x] Azure Data Explorer에 대해 KQL 쿼리 실행
[x] 데이터베이스 리소스를 검색하고 탐색합니다.
[x] 구성된 데이터베이스의 테이블 나열
[x] 테이블 스키마 보기
[x] 테이블의 샘플 데이터
[x] 테이블 통계/세부 정보 가져오기
[x] 인증 지원
[x] 토큰 자격 증명 지원(Azure CLI, MSI 등)
[x] AKS에 대한 워크로드 ID 자격 증명 지원
[x] Docker 컨테이너화 지원
[x] AI 어시스턴트를 위한 대화형 도구 제공
도구 목록은 구성 가능하므로 MCP 클라이언트에서 사용할 도구를 선택할 수 있습니다. 특정 기능을 사용하지 않거나 컨텍스트 창을 너무 많이 차지하고 싶지 않을 때 유용합니다.
Related MCP server: EdgeLake MCP Server
Azure CLI를 사용하여 ADX 클러스터에 대한 권한이 있는 Azure 계정에 로그인합니다.
.env 파일이나 시스템 환경 변수를 통해 ADX 클러스터의 환경 변수를 구성합니다.
지엑스피1
이제 서버는 워크로드 아이덴티티가 구성된 Azure Kubernetes Service(AKS) 환경에서 실행될 때 기본적으로 WorkloadIdentityCredential을 사용합니다. 필요한 환경 변수가 있는 경우 WorkloadIdentityCredential 사용을 우선시합니다.
Azure Workload Identity를 사용하는 AKS의 경우 다음 작업만 수행하면 됩니다.
Pod에 AZURE_TENANT_ID 및 AZURE_CLIENT_ID 환경 변수가 설정되어 있는지 확인하세요.
토큰 파일이 기본 경로에 마운트되었는지 확인하거나 ADX_TOKEN_FILE_PATH 사용하여 사용자 지정 경로를 지정하세요.
이러한 환경 변수가 없으면 서버는 자동으로 DefaultAzureCredential로 되돌아가 여러 인증 방법을 순서대로 시도합니다.
클라이언트 설정 파일에 서버 설정을 추가하세요. 예를 들어, Claude Desktop의 경우:
{
"mcpServers": {
"adx": {
"command": "uv",
"args": [
"--directory",
"<full path to adx-mcp-server directory>",
"run",
"src/adx_mcp_server/main.py"
],
"env": {
"ADX_CLUSTER_URL": "https://yourcluster.region.kusto.windows.net",
"ADX_DATABASE": "your_database"
}
}
}
}참고: Claude Desktop에서
Error: spawn uv ENOENT표시되면uv에 대한 전체 경로를 지정하거나 구성에서 환경 변수NO_UV=1설정해야 할 수 있습니다.
이 프로젝트에는 쉬운 배포와 격리를 위한 Docker 지원이 포함되어 있습니다.
다음을 사용하여 Docker 이미지를 빌드합니다.
docker build -t adx-mcp-server .Docker를 사용하여 여러 가지 방법으로 서버를 실행할 수 있습니다.
docker run -it --rm \
-e ADX_CLUSTER_URL=https://yourcluster.region.kusto.windows.net \
-e ADX_DATABASE=your_database \
-e AZURE_TENANT_ID=your_tenant_id \
-e AZURE_CLIENT_ID=your_client_id \
adx-mcp-serverAzure Data Explorer 자격 증명으로 .env 파일을 만든 다음 다음을 실행합니다.
docker-compose upClaude Desktop과 함께 컨테이너화된 서버를 사용하려면 환경 변수와 함께 Docker를 사용하도록 구성을 업데이트하세요.
{
"mcpServers": {
"adx": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"-e", "ADX_CLUSTER_URL",
"-e", "ADX_DATABASE",
"-e", "AZURE_TENANT_ID",
"-e", "AZURE_CLIENT_ID",
"-e", "ADX_TOKEN_FILE_PATH",
"adx-mcp-server"
],
"env": {
"ADX_CLUSTER_URL": "https://yourcluster.region.kusto.windows.net",
"ADX_DATABASE": "your_database",
"AZURE_TENANT_ID": "your_tenant_id",
"AZURE_CLIENT_ID": "your_client_id",
"ADX_TOKEN_FILE_PATH": "/var/run/secrets/azure/tokens/azure-identity-token"
}
}
}
}이 구성은 -e 플래그와 변수 이름만 사용하여 Claude Desktop에서 Docker 컨테이너로 환경 변수를 전달하고, env 객체에 실제 값을 제공합니다.
이 저장소는 원활한 개발 환경을 위한 개발 컨테이너로도 사용할 수 있습니다. 개발 컨테이너 설정은 devcontainer-feature/adx-mcp-server 폴더에 있습니다.
자세한 내용은 devcontainer README를 확인하세요.
기여를 환영합니다! 제안이나 개선 사항이 있으시면 이슈를 개설하거나 풀 리퀘스트를 제출해 주세요.
이 프로젝트는 uv 사용하여 종속성을 관리합니다. 플랫폼에 맞는 지침에 따라 uv 설치하세요.
curl -LsSf https://astral.sh/uv/install.sh | sh그런 다음 가상 환경을 만들고 다음을 사용하여 종속성을 설치할 수 있습니다.
uv venv
source .venv/bin/activate # On Unix/macOS
.venv\Scripts\activate # On Windows
uv pip install -e .이 프로젝트는 src 디렉토리 구조로 구성되었습니다.
adx-mcp-server/
├── src/
│ └── adx_mcp_server/
│ ├── __init__.py # Package initialization
│ ├── server.py # MCP server implementation
│ ├── main.py # Main application logic
├── Dockerfile # Docker configuration
├── docker-compose.yml # Docker Compose configuration
├── .dockerignore # Docker ignore file
├── pyproject.toml # Project configuration
└── README.md # This file이 프로젝트에는 기능성을 보장하고 회귀를 방지하는 데 도움이 되는 포괄적인 테스트 모음이 포함되어 있습니다.
pytest로 테스트를 실행합니다.
# Install development dependencies
uv pip install -e ".[dev]"
# Run the tests
pytest
# Run with coverage report
pytest --cov=src --cov-report=term-missing테스트는 다음과 같이 구성됩니다.
구성 검증 테스트
서버 기능 테스트
오류 처리 테스트
주요 응용 프로그램 테스트
새로운 기능을 추가할 때, 해당 테스트도 추가해 주세요.
도구 | 범주 | 설명 |
| 질문 | Azure Data Explorer에 대한 KQL 쿼리 실행 |
| 발견 | 구성된 데이터베이스의 모든 테이블 나열 |
| 발견 | 특정 테이블에 대한 스키마 가져오기 |
| 발견 | 선택적 샘플 크기가 있는 테이블에서 샘플 데이터 가져오기 |
MIT
Executes a Kusto Query Language (KQL) query against the configured Azure Data Explorer database and returns the results as a list of dictionaries.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description must disclose behavioral traits. It only states that the tool returns a list of dictionaries but does not mention whether queries can modify data, rate limits, or pagination behavior. The lack of safety disclaimers is a gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that immediately conveys the core action and result format. No unnecessary words or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool (one parameter) and the presence of an output schema (not shown but indicated), the description covers the essential action. However, it lacks usage guidance and behavioral transparency, making it only minimally adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter 'query' has no schema description (0% coverage). The description adds the phrase 'Kusto Query Language (KQL)' which clarifies the language but does not explain expected syntax, format, or examples. The value added beyond the schema is minimal.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool as executing a KQL query against Azure Data Explorer, with a specific verb ('executes') and resource ('KQL query'). It distinguishes itself from siblings like get_table_details by being the only tool that runs arbitrary queries.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like list_tables or sample_table_data. There is no mention of prerequisites, safety considerations, or typical use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieves table details including TotalRowCount, HotExtentSize
| Name | Required | Description | Default |
|---|---|---|---|
| table_name | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It only states 'retrieves', hinting at read-only, but doesn't disclose auth needs, performance impact, or other behavioral traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence is concise, but it is too brief to be fully informative. It could include more detail without being verbose, such as stating it's a read operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Output schema exists, so return values are covered. However, the description lacks context on when to use, parameter details, and behavioral traits, making it incomplete for an agent's decision.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has one parameter (table_name) with 0% description coverage. The description does not explain the parameter format, constraints, or valid values, adding no value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves table details and lists specific metrics (TotalRowCount, HotExtentSize). It distinguishes from sibling tools like get_table_schema (schema) and sample_table_data (samples).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool vs alternatives. Usage is implied by the description of retrieving row count and extent size, but no conditions or exclusions are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieves the schema information for a specified table in the Azure Data Explorer database, including column names, data types, and other schema-related metadata.
| Name | Required | Description | Default |
|---|---|---|---|
| table_name | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must fully disclose behavior. It states the action but does not mention read-only safety, error handling (e.g., if table does not exist), or any prerequisites. For a read operation, minimal but still insufficient given zero annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence that is concise and directly states the purpose. No wasted words, but could be slightly more structured (e.g., separating purpose and details). Still effective and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given presence of output schema, description need not explain return values. For a simple one-parameter tool, the description covers the core function but misses usage guidelines and parameter details. Minimal viable but with clear gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has one parameter (table_name) with 0% description coverage. The tool description does not elaborate on table_name format, expected values, or constraints. With low schema coverage, the description should compensate but fails to add meaning beyond the parameter name.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the verb 'retrieves', the resource 'schema information for a specified table', and includes specifics like 'column names, data types, and other schema-related metadata'. It easily distinguishes from siblings like 'execute_query' (runs queries) and 'list_tables' (lists tables).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. For example, it does not explain that this is for schema metadata only, while 'get_table_details' might include more. Lacks any explicit context or exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieves a list of all tables available in the configured Azure Data Explorer database, including their names, folders, and database associations.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It indicates a read operation (retrieves) without mentioning side effects, auth needs, or rate limits. For a simple list operation, this is minimally adequate but lacks explicit disclosure of read-only behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with verb 'Retrieves'. Every word adds value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Complexity is low (empty schema, 0 parameters). Description covers what the tool returns (table names, folders, database associations). Presence of an output schema reduces burden, and the description aligns well.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has no parameters (100% coverage), so baseline is 3. The description adds no parameter details, which is acceptable since there are none.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool retrieves a list of all tables in the Azure Data Explorer database, specifying the returned fields (names, folders, database associations). This distinguishes it from sibling tools like get_table_details or get_table_schema which focus on individual tables or schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. The description does not mention when to use list_tables instead of execute_query, get_table_details, etc. Context about use cases or exclusions is absent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieves a random sample of rows from the specified table in the Azure Data Explorer database. The sample_size parameter controls how many rows to return (default: 10).
| Name | Required | Description | Default |
|---|---|---|---|
| table_name | Yes | ||
| sample_size | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavior but only mentions sampling and sample_size default. It does not state whether the operation is read-only, the nature of randomness, or implications for large tables. Minimal transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with purpose, no redundant words. Efficiently communicates core function and key parameter.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists, the description need not detail return values, but lacks context like the source database name (implied in description), column selection, or ordering. Sufficient for a simple sampling tool but minimal.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% so description must compensate. It explains sample_size (default 10) but provides no meaning for table_name beyond its existence. Half the parameters are undocumented in meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it retrieves a random sample of rows from a specified table in Azure Data Explorer. It uses a specific verb and resource, and implicitly distinguishes from sibling tools like list_tables or execute_query by specifying sampling behavior.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use when a random sample is needed, but provides no explicit guidance on when to use this tool versus alternatives (e.g., execute_query for custom queries). No when-not or context about prerequisites is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.1.0execute_query1 field changedInput schema / additionalPropertiesAdded value: +falseget_table_details1 field changedInput schema / additionalPropertiesAdded value: +falseget_table_schema1 field changedInput schema / additionalPropertiesAdded value: +falselist_tables1 field changedInput schema / additionalPropertiesAdded value: +falsesample_table_data1 field changedInput schema / additionalPropertiesAdded value: +falsev1.0.0execute_query3 fields changedInput schema / properties / query / titleRemoved value: -"Query"Input schema / titleRemoved value: -"execute_queryArguments"Output schema / (root)Previous value: -nullNew value: +{
+ "properties": {
+ "result": {
+ "items": {
+ "additionalProperties": true,
+ "type": "object"
+ },
+ "type": "array"
+ }
+ },
+ "required": [
+ "result"
+ ],
+ "type": "object",
+ "x-fastmcp-wrap-result": true
+}get_table_detailsget_table_schema3 fields changedInput schema / properties / table_name / titleRemoved value: -"Table Name"Input schema / titleRemoved value: -"get_table_schemaArguments"Output schema / (root)Previous value: -nullNew value: +{
+ "properties": {
+ "result": {
+ "items": {
+ "additionalProperties": true,
+ "type": "object"
+ },
+ "type": "array"
+ }
+ },
+ "required": [
+ "result"
+ ],
+ "type": "object",
+ "x-fastmcp-wrap-result": true
+}list_tables2 fields changedInput schema / titleRemoved value: -"list_tablesArguments"Output schema / (root)Previous value: -nullNew value: +{
+ "properties": {
+ "result": {
+ "items": {
+ "additionalProperties": true,
+ "type": "object"
+ },
+ "type": "array"
+ }
+ },
+ "required": [
+ "result"
+ ],
+ "type": "object",
+ "x-fastmcp-wrap-result": true
+}sample_table_data4 fields changedInput schema / properties / sample_size / titleRemoved value: -"Sample Size"Input schema / properties / table_name / titleRemoved value: -"Table Name"Input schema / titleRemoved value: -"sample_table_dataArguments"Output schema / (root)Previous value: -nullNew value: +{
+ "properties": {
+ "result": {
+ "items": {
+ "additionalProperties": true,
+ "type": "object"
+ },
+ "type": "array"
+ }
+ },
+ "required": [
+ "result"
+ ],
+ "type": "object",
+ "x-fastmcp-wrap-result": true
+}execute_queryget_table_schemalist_tablessample_table_dataScored across 5 tools
Each tool targets a distinct purpose: listing tables, retrieving schema, retrieving details, sampling data, and executing arbitrary queries. No overlap and clear boundaries between tools.
All tool names follow a consistent verb_noun pattern (e.g., list_tables, get_table_schema, execute_query) using snake_case, making them predictable and easy to interpret.
Five tools is well-scoped for a read-only Azure Data Explorer query server, covering essential operations like listing, schema retrieval, details, sampling, and querying without unnecessary clutter.
The tool set provides a solid foundation for querying and metadata retrieval. Missing are data modification or ingestion tools, but for a query-focused server this is acceptable, though a bit more (e.g., table statistics) could enhance completeness.
Ask data questions in natural language. Get SQL, insights, and charts from your databases.
Connect your AI assistants to Keboola and expose your data, transformations, SQL queries, ...
Explore and query your data warehouse through Myriade's AI data analyst agent.
Query your team's drift, vulnerability, and upgrade data from any AI assistant. OAuth 2.1, 51 tools.
