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

Installation

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

Configuration

Environment Variables

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