Penumbra MCP Server

An MCP server providing tools for interacting with the Penumbra blockchain. This server enables privacy-preserving interactions with Penumbra’s core features including transaction queries, validator set information, DEX state, and governance proposals.

Features

Current Tools

• get_validator_set: Get the current validator set information
• get_chain_status: Get current chain status including block height and chain ID
• get_transaction: Get details of a specific transaction
• get_dex_state: Get current DEX state including latest batch auction results
• get_governance_proposals: Get active governance proposals

Planned Features

• Transaction submission
• Private staking operations
• DEX trading (sealed-bid batch auctions)
• Private governance voting
• Liquidity position management

Installation

You can install the package via npm:

npm install @timeheater/penumbra-mcp

Or using yarn:

yarn add @timeheater/penumbra-mcp

Setup

Local Development from Source

1. Install dependencies:

npm install

2. Build the server:

npm run build

3. Run in development mode:

npm run watch

Claude Desktop Integration

To integrate with Claude desktop, add the following configuration to your Claude desktop settings file (~/Library/Application Support/Claude/claude_desktop_config.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"
      }
    }
  }
}

Replace /path/to/penumbra-mcp with the actual path where you’ve installed the server.

Using the MCP Server

Once configured, you can interact with Penumbra through Claude using the following tools:

1. Query validator set:

Tell Claude: "Show me the current Penumbra validator set"

2. Check chain status:

Tell Claude: "What's the current status of the Penumbra chain?"

3. Get transaction details:

Tell Claude: "Look up Penumbra transaction [HASH]"

4. View DEX state:

Tell Claude: "Show me the current Penumbra DEX state"

5. List governance proposals:

Tell Claude: "List active Penumbra governance proposals"

Development

• npm run watch: Watch mode for development
• npm run inspector: Run MCP inspector for testing
• npm test: Run test suite

Environment Variables