home / mcp / penumbra mcp server

Penumbra MCP Server

MCP server for interacting with Penumbra blockchain - providing privacy-preserving tools for chain interaction

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "bmorphism-penumbra-mcp": {
      "command": "node",
      "args": [
        "/Users/barton/infinity-topos/penumbra-mcp/build/index.js"
      ],
      "env": {
        "PENUMBRA_NETWORK": "mainnet",
        "PENUMBRA_CHAIN_ID": "penumbra-1",
        "PENUMBRA_NODE_URL": "https://rpc.penumbra.zone",
        "PENUMBRA_BLOCK_TIME": "6000",
        "PENUMBRA_EPOCH_DURATION": "100",
        "PENUMBRA_REQUEST_RETRIES": "5",
        "PENUMBRA_REQUEST_TIMEOUT": "30000",
        "PENUMBRA_DEX_MIN_LIQUIDITY": "1000",
        "PENUMBRA_DEX_BATCH_INTERVAL": "60000",
        "PENUMBRA_DEX_MAX_PRICE_IMPACT": "0.05",
        "PENUMBRA_GOVERNANCE_MIN_DEPOSIT": "100000",
        "PENUMBRA_GOVERNANCE_VOTING_PERIOD": "1209600000"
      }
    }
  }
}

You run an MCP server that exposes Penumbra blockchain data and governance through standardized tool endpoints. This server lets you query the validator set, chain status, individual transactions, DEX state, and active governance proposals in a privacy-preserving, MCP-compliant way.

How to use

You interact with the Penumbra MCP Server by configuring a client to communicate with the MCP interface. Once the server is running, you can query current validator set information, check the chain status, fetch details for specific transactions, view the latest DEX state, and list active governance proposals. Use your MCP client to issue the appropriate tool requests and to receive structured responses that reflect Penumbra’s data model.

How to install

Prerequisites: Node.js installed on your machine. You also need a working MCP client that can communicate with servers exposing MCP endpoints.

# Install the MCP package for Penumbra
npm install @timeheater/penumbra-mcp

# or using yarn
yarn add @timeheater/penumbra-mcp

Configuration and usage notes

The Penumbra MCP Server provides a development-focused integration with Claude Desktop. To enable this integration, configure the MCP server entry in Claude’s desktop settings to point to your local Penumbra MCP server process. The example below shows how to set up the server to run in a development environment with a node runtime and a direct build index script, along with the necessary Penumbra environment variables.

json
{
  "mcpServers": {
    "penumbra-mcp": {
      "command": "node",
      "args": ["/Users/barton/infinity-topos/penumbra-mcp/build/index.js"],
      "env": {
        "PENUMBRA_NODE_URL": "https://rpc.penumbra.zone",
        "PENUMBRA_NETWORK": "mainnet",
        "PENUMBRA_CHAIN_ID": "penumbra-1",
        "PENUMBRA_REQUEST_TIMEOUT": "30000",
        "PENUMBRA_REQUEST_RETRIES": "5",
        "PENUMBRA_BLOCK_TIME": "6000",
        "PENUMBRA_EPOCH_DURATION": "100",
        "PENUMBRA_DEX_BATCH_INTERVAL": "60000",
        "PENUMBRA_DEX_MIN_LIQUIDITY": "1000",
        "PENUMBRA_DEX_MAX_PRICE_IMPACT": "0.05",
        "PENUMBRA_GOVERNANCE_VOTING_PERIOD": "1209600000",
        "PENUMBRA_GOVERNANCE_MIN_DEPOSIT": "100000"
      }
    }
  }
}

How to interact with the MCP server using Claude

With the server running, you can ask Claude to perform the supported queries. For example, you can request the current validator set, the chain status, a specific transaction, the DEX state, or governance proposals.

Available tools

get_validator_set

Retrieve information about the current validator set for Penumbra.

get_chain_status

Query the current chain status, including block height and chain ID.

get_transaction

Fetch details for a specific Penumbra transaction by hash.

get_dex_state

Obtain the current state of the Penumbra DEX, including latest batch auction results.

get_governance_proposals

List active governance proposals for Penumbra.