convez.ai
MCP Server
DalgoT4D

dalgo-mcp

DalgoT4D/dalgo-mcp

Ver no GitHub
InicialPluginScore · de 0 a 100

MCP server for the Dalgo data platform — lets AI assistants work with data warehouses, pipelines, dbt transformations, dashboards, charts and reports via natural language

Instalação

$npx convez-ai DalgoT4D/dalgo-mcp

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
37%
Último commit
há 3 meses
Versão
v0.2.0
Issues abertas
10
Contribuidores
4

README

A tradução para o português deste README ainda está na fila.

Dalgo MCP Server

CI Python 3.10+ License: MIT MCP

A Model Context Protocol (MCP) server for Dalgo, the open-source data platform for the social sector. It lets AI assistants like Claude work with your data warehouse, ingestion pipelines, dbt transformations, dashboards, charts, and reports through natural language.

Demo: asking Claude which Dalgo pipelines failed recently and why

Claude Code diagnosing a failed pipeline through the Dalgo MCP server — listing pipelines, pulling run logs, and pinpointing the dbt error.

Table of Contents

Features

  • 63 tools covering the full Dalgo platform: warehouse exploration, pipeline orchestration, Airbyte sources and connections, dbt transformations, dashboards, charts, reports, notifications, and documentation search.
  • Interactive MCP Apps — supported hosts render chart results as live visualizations in the chat, not just tables. See Plugin Skills and docs/mcp-apps.md.
  • Dual transport — run locally over stdio for Claude Desktop and Claude Code, or serve remotely over streamable-http for the Anthropic Messages API MCP connector.
  • Multi-user HTTP mode — each request authenticates with the caller's own Dalgo JWT; the server detects their organization automatically.
  • One-command install as a Claude Code plugin.
  • Docker-ready for self-hosted deployments.

Quick Start

The fastest way to get started is the Claude Code plugin:

claude plugin install dalgo

You'll be prompted for your Dalgo API URL, username, password, and organization slug. The plugin configures the MCP server automatically — no further setup needed.

Installation

Requires Python 3.10+ and uv.

git clone https://github.com/DalgoT4D/dalgo-mcp.git
cd dalgo-mcp
cp .env.example .env
# Edit .env with your Dalgo credentials
uv sync

Verify the server starts:

uv run dalgo-mcp

Configuration

All configuration is via environment variables (or a .env file — see .env.example).

VariableRequiredDefaultDescription
DALGO_API_URLYeshttp://localhost:8002Dalgo API base URL
DALGO_USERNAMEstdio only—Dalgo login email
DALGO_PASSWORDstdio only—Dalgo login password
DALGO_ORG_SLUGstdio only—Dalgo organization slug
DALGO_TRANSPORTNostdiostdio or streamable-http
DALGO_HOSTNo0.0.0.0HTTP server bind address
DALGO_PORTNo8080HTTP server port

Usage

Claude Desktop

Add the server to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "dalgo": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/dalgo-mcp", "dalgo-mcp"],
      "env": {
        "DALGO_API_URL": "https://your-dalgo-instance.com",
        "DALGO_USERNAME": "your-email@example.com",
        "DALGO_PASSWORD": "your-password",
        "DALGO_ORG_SLUG": "your-org-slug"
      }
    }
  }
}

Claude Code

If you prefer manual setup over the plugin:

claude mcp add --transport stdio dalgo -- uv run --directory /path/to/dalgo-mcp dalgo-mcp

Credentials are read from the .env file in the project directory.

Anthropic Messages API (remote)

Run the server in streamable-http mode so any user can connect with a URL and their own Dalgo JWT — no local setup required:

DALGO_TRANSPORT=streamable-http \
DALGO_API_URL=https://your-dalgo-instance.com \
DALGO_HOST=0.0.0.0 \
DALGO_PORT=8080 \
uv run dalgo-mcp

Then connect via the MCP connector:

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    mcp_servers=[
        {
            "type": "url",
            "url": "http://your-server:8080/mcp/",
            "name": "dalgo",
            "authorization_token": "<dalgo-jwt-token>",
        }
    ],
    messages=[{"role": "user", "content": "List my pipelines"}],
)

The authorization_token is a Dalgo JWT. Each user passes their own token and the server detects their organization automatically.

Docker

The image runs in streamable-http mode on port 8079 by default.

cp .env.example .env
# Edit .env — at minimum, set DALGO_API_URL

docker build -t dalgo-mcp .
docker run --rm -p 8079:8079 --env-file .env dalgo-mcp

Or with Docker Compose:

docker compose up --build

The server is then reachable at http://localhost:8079/. Point the Anthropic MCP connector at that URL and pass each user's Dalgo JWT as the authorization_token.

Authentication

ModeAuth method
stdioUsername/password from .env; single user
streamable-httpBearer JWT per request; multi-user, org auto-detected via /api/currentuserv2

In HTTP mode the server verifies JWT structure and expiry, while the Dalgo backend validates signatures. Per-token clients are cached, so organization detection happens only once per token.

Tool Reference

ToolDescriptionCategory
dalgo_get_current_userGet the currently authenticated Dalgo user's profile informationOrganization
dalgo_get_feature_flagsGet feature flags enabled for the current Dalgo organizationOrganization
dalgo_list_org_usersList all users in the current Dalgo organizationOrganization
dalgo_get_table_columnsGet column names and types for a specific warehouse tableWarehouse
dalgo_get_table_dataFetch rows from a warehouse table. Defaults to 10 rows to avoid context overflowWarehouse
dalgo_get_table_row_countGet the total row count of a warehouse tableWarehouse
dalgo_list_schemasList all schemas in the connected data warehouseWarehouse
dalgo_list_tablesList all tables in a specific warehouse schemaWarehouse
dalgo_create_pipelineCreate a new orchestration pipelinePipelines
dalgo_delete_pipelineDelete a pipeline by its deployment IDPipelines
dalgo_get_flow_runGet details of a specific flow runPipelines
dalgo_get_flow_run_logsGet logs for a specific flow run. Large logs are truncated to avoid context overflow —Pipelines
dalgo_get_pipelineGet details of a specific pipeline by its deployment IDPipelines
dalgo_get_pipeline_run_historyGet the run history for a specific pipelinePipelines
dalgo_list_pipelinesList all orchestration pipelines (Prefect deployments) in the organizationPipelines
dalgo_trigger_pipeline_runTrigger an immediate run of a pipelinePipelines
dalgo_update_pipelineUpdate an existing pipeline's configurationPipelines
dalgo_delete_sourceDelete a data sourceSources
dalgo_get_sourceGet details of a specific data sourceSources
dalgo_get_sources_modelsGet all available sources and models with their columnsSources
dalgo_list_source_definitionsList all available Airbyte source definitions (connector types)Sources
dalgo_list_sourcesList all configured data sources (Airbyte sources) in the organizationSources
dalgo_get_connectionGet details of a specific Airbyte connectionConnections
dalgo_get_connection_catalogGet the stream catalog for an Airbyte connection (selected streams and sync modes)Connections
dalgo_get_sync_historyGet sync run history for an Airbyte connectionConnections
dalgo_list_connectionsList all Airbyte connections (source-to-destination syncs) in the organizationConnections
dalgo_create_dashboardCreate a new dashboardDashboards
dalgo_delete_dashboardDelete a dashboardDashboards
dalgo_get_dashboardGet details of a specific dashboard including its chartsDashboards
dalgo_list_dashboardsList all dashboards in the organizationDashboards
dalgo_update_dashboardUpdate an existing dashboardDashboards
dalgo_create_chartCreate a new chartCharts
dalgo_delete_chartDelete a chartCharts
dalgo_get_chartGet details of a specific chartCharts
dalgo_get_chart_dataExecute a chart's query and return the resulting dataCharts
dalgo_list_chartsList all charts in the organizationCharts
dalgo_render_chartRender a chart as an interactive visualizationCharts
dalgo_update_chartUpdate an existing chartCharts
dalgo_create_reportCreate a new report (data snapshot)Reports
dalgo_delete_reportDelete a reportReports
dalgo_get_reportView a specific report's dataReports
dalgo_list_reportsList all saved reports (data snapshots) in the organizationReports
dalgo_acquire_canvas_lockAcquire a lock on the transform canvas. Required before making any canvas modificationsTransforms
dalgo_add_source_to_canvasAdd an existing source or model to the canvas as a nodeTransforms
dalgo_create_operationCreate a new operation node on the canvas (join, filter, rename, aggregate, etc.)Transforms
dalgo_edit_operationEdit an existing operation node on the canvasTransforms
dalgo_get_data_typesGet the list of warehouse-specific data types (used for cast operations)Transforms
dalgo_get_dbt_workspaceGet the dbt workspace configuration for the organizationTransforms
dalgo_get_git_statusGet the git status of the dbt project repository (modified/untracked files)Transforms
dalgo_get_node_columnsGet column names and data types for a specific canvas nodeTransforms
dalgo_get_node_detailsGet full details of a canvas node including its operation config and input nodesTransforms
dalgo_get_transform_graphGet the dbt project DAG (directed acyclic graph) showing model dependenciesTransforms
dalgo_publish_changesCommit and push dbt project changes to gitTransforms
dalgo_release_canvas_lockRelease the lock on the transform canvas after modifications are completeTransforms
dalgo_run_dbtTrigger a dbt run via Celery (async task). Optionally pass command and flagsTransforms
dalgo_sync_sourcesSync dbt sources from the connected warehouse, updating the dbt project's source definitionsTransforms
dalgo_terminate_chainMaterialize an operation chain into a dbt modelTransforms
dalgo_get_unread_countGet the count of unread notificationsNotifications
dalgo_list_notificationsList recent notifications for the current userNotifications
dalgo_mark_notifications_readMark notifications as readNotifications
dalgo_get_docFetch and return the full content of a Dalgo documentation pageDocumentation
dalgo_list_docsList all Dalgo documentation pages grouped by sectionDocumentation
dalgo_search_docsSearch Dalgo documentation by keywordDocumentation

The table above is auto-generated. After adding or changing tools, regenerate it with:

uv run python scripts/generate_tool_table.py

MCP Apps

The server ships an MCP Apps (SEP-1865) interactive view. On hosts that support the extension — Claude, Claude Desktop, VS Code Copilot, and others — calling dalgo_render_chart renders the chart as a live SVG visualization (bar, line, pie, or big-number) inside the conversation instead of a JSON table. Hosts without MCP Apps support fall back to the tool's structured data unchanged.

The view (src/dalgo_mcp/apps/chart_view.html) is self-contained and dependency-free, runs in a sandboxed iframe, and receives PII-masked data from the server. See docs/mcp-apps.md for the architecture, the SEP-1865 contract, and the roadmap for further Apps (pipeline run board, dbt DAG viewer, data grid).

Plugin Skills

When installed as a Claude Code plugin, the server ships with Agent Skills — workflow guidance that teaches the assistant how to use the tools correctly, not just what they are (modeled on preset-io/agent-skills).

SkillCovers
dalgo-mcpRouting requests to the right domain skill; staying on MCP tools
dalgo-warehouseExploring schemas, tables, columns, and sample data safely
dalgo-pipelinesThe trigger → poll → verify loop; never reporting "triggered" as "succeeded"
dalgo-ingestionAirbyte sources, connections, sync history, and sync-failure triage
dalgo-transformsThe canvas lock protocol, dbt runs, and plain-language dbt error translation
dalgo-visualizationBuilding charts before dashboards; validating chart queries
dalgo-troubleshootingEvidence-first failure diagnosis and notifications

Each skill is a skills/<name>/SKILL.md with optional references/ for tool tables and failure-triage patterns.

Development

# Install with dev dependencies
uv sync --extra dev

# Run the test suite
uv run pytest

# Lint
uv run ruff check .

# Format check
uv run ruff format --check .

CI runs lint and tests on every push to main and on all pull requests.

Project Structure

.claude-plugin/
└── plugin.json      # Claude Code plugin manifest
.mcp.json            # MCP server config for plugin mode
scripts/
├── generate_tool_table.py   # Regenerates the README tool table
└── measure_token_cost.py    # Measures tool-schema token footprint
src/dalgo_mcp/
├── config.py        # Environment config and validation
├── auth.py          # JWT token verifier for HTTP mode
├── client.py        # Async Dalgo API client with auto-auth
├── server.py        # FastMCP app, dual transport, client resolution
├── login.py         # Username/password login flow
├── oauth.py         # OAuth flow
├── pii.py           # PII handling utilities
└── tools/
    ├── organization.py
    ├── warehouse.py
    ├── pipelines.py
    ├── sources.py
    ├── connections.py
    ├── dashboards.py
    ├── charts.py
    ├── reports.py
    ├── transforms.py
    ├── notifications.py
    └── docs.py
tests/               # Pytest suite

Releases

This project follows Semantic Versioning. Every release is tagged as v<version> and documented in the CHANGELOG; see the releases page for downloadable artifacts and notes.

Release process:

  1. Bump version in pyproject.toml and add a section to CHANGELOG.md.
  2. Commit, then tag: git tag v<version> && git push origin v<version>.
  3. The publish workflow builds the package and publishes it to PyPI automatically.
  4. Create a GitHub release from the tag with the changelog notes.

Contributing

Contributions are welcome! To get started:

  1. Fork the repository and create a feature branch.
  2. Make your changes, keeping ruff clean and tests passing (uv run ruff check . && uv run pytest).
  3. If you added or changed tools, regenerate the tool table (uv run python scripts/generate_tool_table.py).
  4. Open a pull request with a clear description of the change.

Found a bug or have a feature request? Please open an issue.

About Dalgo

Dalgo is an open-source data platform built by Project Tech4Dev for the social sector, combining data ingestion (Airbyte), transformation (dbt), orchestration (Prefect), and visualization in one place.

License

Released under the MIT License.

Ver o original no GitHub

Bom para

Relacionados