Skip to main content
Glama

koios-mcp

An MCP (Model Context Protocol) server for the Koios Cardano blockchain REST API. Provides LLMs with direct access to on-chain Cardano data through 95 tools covering every non-deprecated Koios endpoint.

What is Koios?

Koios is a decentralized and open-source public API query layer for the Cardano blockchain. It provides RESTful access to blockchain data without requiring complex infrastructure, built on top of PostgREST.

Related MCP server: IndigoProtocol/cardano-mcp

Features

  • 95 tools across 11 endpoint categories

  • All Cardano networks: Mainnet, Preview, Preprod, Guild

  • Full PostgREST support: Vertical/horizontal filtering, pagination, ordering

  • Optional authentication: Works without auth; supports Bearer tokens for higher rate limits

Tools

Category

Tools

Description

Network

8

Chain tip, genesis params, tokenomics, protocol params, era summaries

Epoch

3

Epoch info, protocol params per epoch, block protocol distribution

Block

4

Block listing, block details, block transactions, raw CBOR

Transaction

9

TX info/status/metadata, UTxO info, submit TX, CBOR data

Address

8

Address info/UTxOs/assets/transactions, credential lookups

Account

11

Stake account info/rewards/history/delegations/assets

Asset

11

Native asset listing/info/history/holders, policy lookups, NFT address

Pool

17

Pool listing/info/delegators/blocks/history/metadata/relays/voting

Governance

14

DReps, committee info, proposals, votes, voting power history

Script

6

Script info, native/Plutus listings, redeemers, datum info

Ogmios

1

Proxy to Ogmios JSON-RPC queries

Installation

git clone https://github.com/michaeljfazio/koios-mcp.git
cd koios-mcp
npm install
npm run build

Configuration

Environment Variables

Variable

Default

Description

KOIOS_NETWORK

preview

Network to query: mainnet, preview, preprod, or guild

KOIOS_API_KEY

—

Optional Bearer token for higher rate limits (get one here)

Claude Code

Add to your Claude Code MCP settings (~/.claude/settings.json or project .mcp.json):

{
  "mcpServers": {
    "koios": {
      "command": "node",
      "args": ["/path/to/koios-mcp/dist/index.js"],
      "env": {
        "KOIOS_NETWORK": "preview"
      }
    }
  }
}

Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "koios": {
      "command": "node",
      "args": ["/path/to/koios-mcp/dist/index.js"],
      "env": {
        "KOIOS_NETWORK": "mainnet"
      }
    }
  }
}

Usage Examples

Once connected, an LLM can use tools like:

  • koios_tip — Get the latest block on the chain

  • koios_tx_info — Get detailed transaction info by hash

  • koios_address_info — Look up balance and UTxOs for an address

  • koios_asset_info — Get metadata and minting history for native assets

  • koios_pool_info — Get stake pool details

  • koios_drep_info — Look up delegated representative information

  • koios_proposal_list — Browse governance proposals

PostgREST Query Features

Most GET-based tools support PostgREST query parameters for flexible data retrieval:

  • select — Return only specific columns: "block_height,epoch_no,hash"

  • order — Sort results: "block_height.desc"

  • limit / offset — Paginate results

  • Horizontal filters — Filter by column values using operators like eq, gt, lt, gte, lte, neq, like, in

Development

# Watch mode with auto-reload
npm run dev

# Build
npm run build

# Run
npm start

API Rate Limits

Koios public tier (no auth):

  • 100 requests per 10 seconds per IP

  • 1000 rows max per paginated response

  • 30 second query timeout

  • 1 KB request body size limit (5 KB for authenticated)

License

MIT

Available Tools

92 tools
koios_account_addressesB

Get all payment addresses associated with given stake accounts

Inputs: _stake_addresses (required), limit, order, _empty, +3 more.

koios_account_assetsB

Get native asset holdings for given stake accounts

Inputs: _stake_addresses (required), limit, order, offset, +1 more.

koios_account_infoB

Get stake account information including balance, delegation, and rewards for given stake addresses

Inputs: _stake_addresses (required), limit, order, offset, +1 more.

koios_account_info_cachedA

Get cached stake account information (faster but may be slightly stale)

Inputs: _stake_addresses (required), limit, order, offset, +1 more.

koios_account_listA

Get a list of all stake accounts on the Cardano blockchain

Inputs: limit, order, offset, select.

koios_account_reward_historyC

Get reward history for given stake accounts

Inputs: _stake_addresses (required), limit, order, offset, +2 more.

koios_account_stake_historyB

Get stake history (active stake per epoch) for given stake accounts

Inputs: _stake_addresses (required), limit, order, offset, +2 more.

koios_account_txsC

Get transaction history for a specific stake account

Inputs: _stake_address (required), limit, order, offset, +2 more.

koios_account_update_historyC

Get full update history for given stake accounts

Inputs: _stake_addresses (required), limit, order, offset, +1 more.

koios_account_updatesB

Get account registration/deregistration updates for given stake accounts

Inputs: _stake_addresses (required), limit, order, offset, +1 more.

koios_account_utxosC

Get UTxOs associated with given stake accounts

Inputs: _stake_addresses (required), limit, order, offset, +2 more.

koios_address_assetsC

Get native asset holdings for given addresses

Inputs: _addresses (required), limit, order, offset, +1 more.

koios_address_infoB

Get balance and staking information for given addresses

Inputs: _addresses (required), limit, order, offset, +1 more.

koios_address_listB

Get a list of all addresses with their first appearance on the blockchain

Inputs: limit, order, offset, select.

koios_address_outputsA

Get transaction outputs for given addresses (including spent)

Inputs: _addresses (required), limit, order, offset, +2 more.

koios_address_txsB

Get transaction hashes for given addresses

Inputs: _addresses (required), limit, order, offset, +2 more.

koios_address_utxosC

Get UTxO set for given addresses

Inputs: _addresses (required), limit, order, offset, +2 more.

koios_asset_addressesA

Get all addresses holding a specific asset

Inputs: _asset_policy (required), limit, order, offset, +2 more.

koios_asset_historyB

Get mint/burn history of a specific asset

Inputs: _asset_policy (required), limit, order, offset, +2 more.

koios_asset_infoC

Get detailed information about specific assets

Inputs: _asset_list (required), limit, order, offset, +2 more.

koios_asset_listC

Get a list of all native assets on the Cardano blockchain

Inputs: limit, order, offset, select.

koios_asset_nft_addressB

Get the current address holding a specific NFT

Inputs: _asset_policy (required), limit, order, offset, +2 more.

koios_asset_summaryB

Get a summary of a specific asset (total transactions, wallets, mints/burns)

Inputs: _asset_policy (required), limit, order, offset, +2 more.

koios_asset_token_registryB

Get asset information from the token registry (off-chain metadata)

Inputs: limit, order, offset, select.

koios_asset_txsC

Get transactions involving a specific asset

Inputs: _asset_policy (required), limit, order, offset, +4 more.

koios_asset_utxosB

Get UTxOs containing specific assets

Inputs: _asset_list (required), limit, order, offset, +2 more.

koios_block_infoB

Get detailed information about specific blocks by their hashes

Inputs: _block_hashes (required), limit, order, offset, +1 more.

koios_blocksB

Get a list of blocks, latest first, with pagination support

Inputs: limit, order, offset, select.

koios_block_tx_cborC

Get raw CBOR-encoded transactions from specific blocks

Inputs: _block_hashes (required), limit, order, offset, +1 more.

koios_block_txsA

Get a list of all transactions included in specific blocks

Inputs: _block_hashes (required), limit, order, offset, +1 more.

koios_cli_protocol_paramsC

Get the current protocol parameters in cardano-cli compatible format

Inputs: limit, order, offset, select.

koios_committee_infoC

Get Constitutional Committee member information

Inputs: limit, order, offset, select, +1 more.

koios_committee_votesB

Get Constitutional Committee votes on governance proposals

Inputs: limit, order, offset, select, +1 more.

koios_credential_txsA

Get transaction hashes for given payment credentials

Inputs: _payment_credentials (required), limit, order, offset, +2 more.

koios_credential_utxosB

Get UTxO set for given payment credentials

Inputs: _payment_credentials (required), limit, order, offset, +2 more.

koios_datum_infoA

Get datum information for given datum hashes

Inputs: _datum_hashes (required), limit, order, offset, +1 more.

koios_drep_delegatorsA

Get current delegators for a specific DRep

Inputs: _drep_id (required), limit, order, offset, +1 more.

koios_drep_epoch_summaryC

Get DRep epoch summary statistics

Inputs: limit, order, offset, select, +1 more.

koios_drep_infoC

Get detailed information about specific DReps

Inputs: _drep_ids (required), limit, order, offset, +1 more.

koios_drep_listB

Get a list of all registered DReps (Delegated Representatives)

Inputs: limit, order, offset, select.

koios_drep_metadataC

Get metadata for specific DReps

Inputs: _drep_ids (required), limit, order, offset, +1 more.

koios_drep_updatesB

Get registration/update events for DReps

Inputs: limit, order, offset, select, +1 more.

koios_drep_voting_power_historyB

Get voting power history for a specific DRep

Inputs: _drep_id (required), limit, order, offset, +2 more.

koios_epoch_block_protocolsB

Get the block protocol distribution for a specific epoch

Inputs: limit, order, offset, select, +1 more.

koios_epoch_infoA

Get epoch-specific information including start/end times, block counts, and transaction counts

Inputs: limit, order, offset, select, +2 more.

koios_epoch_paramsC

Get protocol parameters for a specific epoch

Inputs: limit, order, offset, select, +1 more.

koios_era_summariesB

Get a summary of all eras on the Cardano blockchain

Inputs: limit, order, offset, select.

koios_genesisC

Get the genesis parameters of the Cardano blockchain

Inputs: limit, order, offset, select.

koios_native_script_listA

Get a list of all native (non-Plutus) scripts on the blockchain

Inputs: limit, order, offset, select.

koios_ogmiosA

Send a JSON-RPC request to the Ogmios endpoint via Koios (supports Ogmios methods like queryLedgerState, queryNetwork, etc.)

Inputs: method (required), params.

koios_param_updatesB

Get protocol parameter update proposals submitted on-chain

Inputs: limit, order, offset, select.

koios_plutus_script_listB

Get a list of all Plutus scripts on the blockchain

Inputs: limit, order, offset, select.

koios_policy_asset_listB

Get a list of all assets minted under a given policy

Inputs: _asset_policy (required), limit, order, offset, +1 more.

koios_policy_asset_mintsA

Get all mint/burn events for assets under a specific policy

Inputs: _asset_policy (required), limit, order, offset, +1 more.

koios_pool_blocksB

Get blocks minted by a specific pool

Inputs: _pool_bech32 (required), limit, order, offset, +2 more.

koios_pool_calidus_keysC

Get Calidus keys for stake pools

Inputs: limit, order, offset, select.

koios_pool_delegatorsB

Get current delegators for a specific pool

Inputs: _pool_bech32 (required), limit, order, offset, +1 more.

koios_pool_delegators_historyB

Get historical delegators for a specific pool

Inputs: _pool_bech32 (required), limit, order, offset, +2 more.

koios_pool_groupsA

Get pool groups (pools sharing the same owner/reward accounts)

Inputs: limit, order, offset, select.

koios_pool_historyC

Get historical performance data for a specific pool

Inputs: _pool_bech32 (required), limit, order, offset, +2 more.

koios_pool_infoC

Get detailed information about specific stake pools

Inputs: _pool_bech32_ids (required), limit, order, offset, +1 more.

koios_pool_invalid_delegatorsB

Get invalid delegators for a specific pool

Inputs: _pool_bech32 (required), limit, order, offset, +2 more.

koios_pool_listB

Get a list of all registered stake pools

Inputs: limit, order, offset, select.

koios_pool_metadataC

Get metadata for specific stake pools

Inputs: _pool_bech32_ids (required), limit, order, offset, +1 more.

koios_pool_owner_historyB

Get owner history for specific pools

Inputs: _pool_bech32_ids (required), limit, order, offset, +1 more.

koios_pool_registrationsB

Get pool registrations for a specific epoch or all epochs

Inputs: limit, order, offset, select, +1 more.

koios_pool_relaysB

Get a list of registered pool relays

Inputs: limit, order, offset, select.

koios_pool_retirementsB

Get pool retirements for a specific epoch or all epochs

Inputs: limit, order, offset, select, +1 more.

koios_pool_stake_snapshotB

Get stake snapshot for a specific pool (mark, set, go snapshots)

Inputs: _pool_bech32 (required), limit, order, offset, +1 more.

koios_pool_updatesB

Get pool registration/update/retirement certificates

Inputs: limit, order, offset, select, +1 more.

koios_pool_voting_power_historyC

Get voting power history for stake pools

Inputs: limit, order, offset, select, +2 more.

koios_proposal_listA

Get a list of all governance proposals

Inputs: limit, order, offset, select.

koios_proposal_votesB

Get all votes cast on a specific governance proposal

Inputs: _proposal_id (required), limit, order, offset, +1 more.

koios_proposal_voting_summaryC

Get voting summary for a specific governance proposal

Inputs: _proposal_id (required), limit, order, offset, +1 more.

koios_reference_script_utxosA

Get UTxOs containing reference scripts for given script hashes

Inputs: _script_hashes (required), limit, order, offset, +1 more.

koios_reserve_withdrawalsC

Get reserve withdrawals from the Cardano reserve

Inputs: limit, order, offset, select.

koios_script_infoB

Get information about specific scripts by their hashes

Inputs: _script_hashes (required), limit, order, offset, +1 more.

koios_script_redeemersB

Get redeemer information for a specific script

Inputs: _script_hash (required), limit, order, offset, +1 more.

koios_submittxA

Submit an already serialized transaction (CBOR-encoded hex string) to the Cardano network

Inputs: tx_cbor_hex (required).

koios_tipB

Get the current chain tip (latest block) of the Cardano blockchain

Inputs: limit, order, offset, select.

koios_totalsB

Get tokenomic statistics (supply, staking, treasury, reserves) per epoch

Inputs: limit, order, offset, select, +1 more.

koios_treasury_withdrawalsB

Get treasury withdrawals from the Cardano treasury

Inputs: limit, order, offset, select.

koios_tx_by_metalabelC

Get transactions by metadata label

Inputs: _label (required), limit, order, offset, +2 more.

koios_tx_cborA

Get raw CBOR-encoded transactions by their hashes

Inputs: _tx_hashes (required), limit, order, offset, +1 more.

koios_tx_infoB

Get detailed information about specific transactions including inputs, outputs, metadata, assets, etc.

Inputs: _tx_hashes (required), limit, order, _certs, +9 more.

koios_tx_metadataC

Get metadata for specific transactions

Inputs: _tx_hashes (required), limit, order, offset, +1 more.

koios_tx_metalabelsC

Get a list of all transaction metadata labels

Inputs: limit, order, offset, select.

koios_tx_outs_epochB

Get all transaction outputs for a specific epoch

Inputs: _epoch_no (required), limit, order, offset, +1 more.

koios_tx_statusA

Get the status (number of confirmations) of given transactions

Inputs: _tx_hashes (required), limit, order, offset, +1 more.

koios_utxo_infoB

Get UTxO information for given UTxO references (tx_hash#tx_index format)

Inputs: _utxo_refs (required), limit, order, offset, +2 more.

koios_vote_listC

Get a list of all governance votes

Inputs: limit, order, offset, select.

koios_voter_proposal_listB

Get governance proposals relevant to a specific voter

Inputs: limit, order, offset, select, +1 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.1/5.0

    Scored across 92 tools

    Disambiguation3/5

    The tools are grouped by domain and mostly have distinct purposes, but the sheer number of similar resources (e.g., koios_account_updates vs koios_account_update_history, koios_pool_registrations vs koios_pool_updates) creates potential confusion. Descriptions help, but boundaries between some tools are subtle.

    Naming Consistency4/5

    All tools consistently use the 'koios_' prefix with snake_case, and most follow a resource_qualifier pattern (e.g., koios_epoch_info, koios_block_txs). Minor deviations like koios_ogmios and embedded abbreviations (cli, cbor) prevent a perfect score.

    Tool Count2/5

    With 92 tools, the server is far beyond the typical well-scoped MCP range. While the Koios API is broad, exposing every endpoint as a separate tool makes the surface unwieldy and overwhelming for agents.

    Completeness5/5

    The toolset offers comprehensive coverage of the Cardano blockchain, including chain status, epochs, blocks, transactions, addresses, accounts, assets, pools, governance, scripts, and even transaction submission. No significant gaps are apparent.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers