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.

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