diavgeia-cli

TypeScript client, CLI, and MCP server for the Diavgeia (Greek Government Transparency) API. Access 71+ million government decisions from every Greek institution since 2010.

• MCP Server: Use with Claude Desktop, Claude Code, Cursor, or any MCP-compatible AI agent — ask questions in natural language
• CLI: Search, browse organizations, look up decisions — from your terminal
• Library: TypeScript client with full type coverage for building your own tools
• Dual format: Ships ESM + CJS with TypeScript declarations

Use with AI agents (MCP)

The fastest way to explore Greek government data: connect to an AI agent and just ask questions in Greek.

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or ~/.config/Claude/claude_desktop_config.json (Linux):

{
  "mcpServers": {
    "diavgeia": {
      "command": "npx",
      "args": ["-y", "-p", "@schemalabs/diavgeia-cli", "diavgeia-mcp"]
    }
  }
}

Claude Code

claude mcp add diavgeia -- npx -y -p @schemalabs/diavgeia-cli diavgeia-mcp

What you can ask

Once connected, just ask in natural language:

• "Τι αποφάσισε ο δήμος Χαλανδρίου για τα σχολεία τον Μάρτιο 2026;"
• "Βρες συμβάσεις πάνω από 100.000€ στο υπουργείο Παιδείας"
• "Ποιες αποφάσεις βγήκαν για το κυλικείο του 12ου δημοτικού;"
• "Δώσε μου το PDF της απόφασης 9Β3ΘΩΗΔ-ΚΝΑ"

The AI agent handles organization lookup, date ranges, search queries, and pagination automatically.

Available tools

Tool	Description
search_organizations	Find government bodies by name (municipalities, ministries, etc.)
search_decisions	Search decisions by org, date, subject, amount, content
get_decision	Get full details for a decision by ADA
get_organization_units	List departments within an organization
list_decision_types	Browse decision type categories
get_document_url	Get PDF and web page links for a decision

Install (CLI)

npm install -g @schemalabs/diavgeia-cli

Or use directly with npx:

npx @schemalabs/diavgeia-cli search query --org 6104 --from 2024-12-01 --to 2024-12-31

Library usage

import { Diavgeia, msToISODate } from 'diavgeia-cli';

const client = new Diavgeia();

// List all municipalities
const orgs = await client.organizations({ category: 'MUNICIPALITY' });

// Search decisions
const results = await client.search({
  org: '6104',
  unit: '81689',
  from_issue_date: '2024-12-01',
  to_issue_date: '2024-12-31',
  status: 'PUBLISHED',
});

for (const d of results.decisions) {
  console.log(`${d.ada} ${msToISODate(d.issueDate)} ${d.subject}`);
}

// Stream all results with async iteration
for await (const decision of client.searchAll({ org: '6104', status: 'PUBLISHED' })) {
  console.log(decision.ada);
}

// Look up a single decision by ADA
const decision = await client.decision('ΨΘ82ΩΡΦ-7ΑΙ');

// Get organization details with units, signers, positions
const details = await client.organizationDetails('6104');

Constructor options

const client = new Diavgeia({
  baseUrl: 'https://test3.diavgeia.gov.gr',  // default: production
  timeout: 60000,                              // default: 30000ms
  fetch: customFetch,                          // default: globalThis.fetch
});

Error handling

import { Diavgeia, DiavgeiaError, DiavgeiaTimeoutError } from 'diavgeia-cli';

try {
  await client.decision('INVALID');
} catch (err) {
  if (err instanceof DiavgeiaError) {
    console.error(`API error ${err.status}: ${err.message}`);
  } else if (err instanceof DiavgeiaTimeoutError) {
    console.error('Request timed out');
  }
}

CLI usage

diavgeia <command> [options]

Global options: --json (force JSON output), --base-url <url>, --timeout <ms>, --version, --help

Output is JSON when piped or --json is passed. Human-readable tables on TTY.

Organizations

# List all municipalities
diavgeia orgs list --category MUNICIPALITY

# Get a specific organization
diavgeia orgs get 6104

# List units (departments) for an organization
diavgeia orgs units 6104

# List all signers for an organization
diavgeia orgs signers 6104

Decisions

# Look up a decision by ADA
diavgeia decisions get ΨΘ82ΩΡΦ-7ΑΙ

# Get a specific version
diavgeia decisions version <version-uuid>

# View version/correction history
diavgeia decisions history ΨΘ82ΩΡΦ-7ΑΙ

# Download decision PDFs
diavgeia decisions download ΨΘ82ΩΡΦ-7ΑΙ

# Download multiple PDFs to a directory, skipping already downloaded
diavgeia decisions download ΨΘ82ΩΡΦ-7ΑΙ Ψ123ΩΡΦ-ΑΒΓ -o ./pdfs --skip-existing

Search

# Search by organization, unit, and date range
diavgeia search query --org 6104 --unit 81689 --from 2024-12-01 --to 2024-12-31

# Free-text search
diavgeia search query --query "προϋπολογισμού" --org 6104

# Search by subject words (tokenized AND-matching, finds word variations)
diavgeia search query --subject-words "δαπάνη προμήθεια" --org 6104

# Search within PDF content
diavgeia search query --content "αποφασίζει" --org 6104

# Filter by financial amount range
diavgeia search query --amount-min 10000 --amount-max 50000 --org 6104

# Fetch ALL results (paginates automatically)
diavgeia search query --org 6104 --from 2024-01-01 --to 2024-12-31 --all

# Wide date ranges are auto-split into 180-day windows; disable with:
diavgeia search query --org 6104 --from 2020-01-01 --to 2024-12-31 --all --no-window

# Advanced search with Lucene syntax
diavgeia search advanced 'organizationUid:"6104" AND issueDate:[DT(2024-01-01T00:00:00) TO DT(2024-12-31T23:59:59)]'

# List searchable fields
diavgeia search terms
diavgeia search terms --common

Reference data

# Decision type taxonomy
diavgeia types

# Details for a specific type (including extra field schema)
diavgeia types get Β.1.1

# List all dictionaries
diavgeia dictionaries

# Get items in a dictionary
diavgeia dictionaries get ORG_CATEGORY

# All position types
diavgeia positions

# Direct lookups
diavgeia units get 81689
diavgeia signers get 100009559

API methods

Method	Description
organizations(params?)	List/filter organizations
organization(orgId)	Get single organization
organizationDetails(orgId)	Organization with units, signers, positions
units(orgId, params?)	List units for organization
signers(orgId)	List signers for organization
orgPositions(orgId)	List positions for organization
unit(unitId)	Get unit by ID
signer(signerId)	Get signer by ID
decision(ada)	Get decision by ADA
decisionVersion(versionId)	Get specific version
versionLog(ada)	Decision version history
downloadDocument(ada)	Download decision PDF (returns ArrayBuffer + checksum)
search(params)	Search with named parameters
searchAdvanced(params)	Search with Lucene syntax
searchAll(params)	Async iterable over all pages
searchTerms()	List all searchable fields
searchTermsCommon()	List common searchable fields
decisionTypes()	Decision type taxonomy
decisionTypeDetails(typeId)	Type with extra field schema
dictionaries()	List all dictionaries
dictionary(name)	Get dictionary items
positions()	All position types

Key concepts

• ADA — Unique decision identifier (Greek letters + numbers, e.g., ΨΘ82ΩΡΦ-7ΑΙ)
• Organization — Government body (e.g., municipality). Identified by numeric UID.
• Unit — Department within an organization (e.g., Municipal Council)
• Timestamps — The API returns milliseconds since epoch. Use msToISODate() to convert.
• Dual base paths — The API uses /luminapi/opendata for structural data and /opendata for search. The client handles this transparently.

Documentation

• API Guide — Complete Diavgeia API reference
• Examples — Practical recipes and patterns

License

MIT