Skip to main content
Glama
grynn-in

konsol-mcp

by grynn-in
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

konsol-cli

Command-line client for configuring the konsol Frappe app.

All configuration goes through konsol — never dbt or ClickHouse directly.

Install

cd konsol_cli
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

Optional MCP server:

pip install -e ".[mcp]"

Related MCP server: Frappe MCP

Two ways to connect

1. Local Docker (default)

Talks to konsol by running bench execute inside your Docker stack.

konsol dimension list --compose-file ../repo/docker-compose.yml

2. Remote HTTP API

Talks to any running konsol site over the Frappe API. Use this from your laptop against a remote server, in CI, or with MCP.

First, create API keys in Frappe:

  1. Log into the site as an EPM Admin user

  2. Go to User → your user → Settings tab → API Access

  3. Click Generate Keys and save the key + secret

Then run commands:

konsol --backend api \
  --url http://localhost:8069 \
  --site konsolidat.local \
  --api-key YOUR_KEY \
  --api-secret YOUR_SECRET \
  dimension list

When connecting to localhost:8069, keep --site set — the CLI sends it as the Host header so Frappe routes to the right site.

Optional config file — copy config.example.toml to ~/.config/konsol/config.toml (connection settings only).

Credentials (pick one, never commit):

cp secrets.example.env ~/.config/konsol/secrets.env && chmod 600 ~/.config/konsol/secrets.env
# or: secrets.example.toml → ~/.config/konsol/secrets.toml

The CLI loads secrets.env first, then secrets.toml. Shell env vars take precedence.

Grok MCP — configs use ${KONSOL_API_KEY} placeholders. Before starting Grok:

source scripts/load-konsol-secrets.sh   # exports vars, does not print them
grok mcp doctor konsol

See .grok/config.toml (project-scoped, safe to commit) — not plaintext secrets.

Commands

# Dimensions
konsol dimension list
konsol dimension show dim_cost_center
konsol dimension create dim_project --source-column Project --label "Project"
konsol dimension publish dim_project
konsol dimension unpublish dim_project

# Measures
konsol measure list
konsol measure create period_headcount --expression "sum(headcount)" --label "Headcount"
konsol measure unpublish period_headcount

# Fact tables
konsol fact list
konsol fact show headcount
konsol fact create my_fact --label "My Fact" --source-type Statistical \
  --clickhouse-table epm_staging.fact_x --scenario-key statistical
konsol fact publish my_fact
konsol fact unpublish my_fact

# Connectors & ERP sources
konsol connector list
konsol connector show CONN-00001
konsol connector create --name "ERPNext Demo" --erp-type erpnext --entity-id ENT01
konsol connector delete CONN-00001
konsol source list

# Config (GitOps YAML)
konsol config export -o model.yaml
konsol config diff model.yaml
konsol config apply model.yaml [--publish] [--prune] [--dry-run]

# Schema
konsol schema apply
konsol schema status

MCP (AI clients)

Install the optional extra, then add mcp.example.json to your MCP client config (Cursor, Claude Desktop, etc.):

pip install -e ".[mcp]"

Set KONSOL_URL, KONSOL_SITE, KONSOL_API_KEY, and KONSOL_API_SECRET in the server env block, then run konsol-mcp (stdio transport).

Connector Airbyte tools (v0.10.0+): test_connector_writeback, provision_connector_airbyte — require the matching konsol app endpoints on your site.

Debug with the MCP Inspector:

npx @modelcontextprotocol/inspector konsol-mcp

Environment variables

Variable

Purpose

KONSOL_BACKEND

bench (default) or api

KONSOL_SITE

Frappe site name

KONSOL_URL

Site URL for api backend

KONSOL_API_KEY

Frappe API key

KONSOL_API_SECRET

Frappe API secret

KONSOL_COMPOSE_FILE

Path to docker-compose.yml for bench backend

Docker deploy note

bench get-app installs konsol from git HEAD, not uncommitted files. Commit konsol changes before docker compose build frappe_backend.

Architecture

konsol-cli / konsol-mcp
  → bench execute  or  HTTP /api/method/konsol.cli_api.*
  → konsol.config_service  →  Frappe DocTypes
  → publish / apply_schema  →  dbt vars, ClickHouse DDL, Pipeline Build Request

Tests

cd konsol_cli && .venv/bin/python -m pytest tests/ -q
cd repo/docker/frappe/konsol && PYTHONPATH=konsol .venv/bin/python -m pytest konsol/tests/test_config_service.py -q

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityStale
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • erpnext-server

    rakeshgangwar
    A
    license
    B
    quality
    F
    maintenance
    This is a TypeScript-based MCP server that provides integration with ERPNext/Frappe API. It enables AI assistants to interact with ERPNext data and functionality through the Model Context Protocol.
    6
    118
    MIT

  • Legion Database MCP Server

    fastmcp-me
    A
    license
    Not graded
    quality
    D
    maintenance
    A unified MCP server for querying and managing multiple database types (PostgreSQL, MySQL, SQL Server, etc.) via natural language through AI assistants.
    GPL 3.0