MCP Generator
The stellar-mcp-generator is a Stellar CLI plugin that generates complete MCP (Model Context Protocol) servers from deployed Soroban smart contracts. It enables AI agents like Claude to interact with your smart contracts through standardized MCP tools.
What It Does
Given a deployed Soroban contract, the generator:
- Fetches the contract specification from the blockchain
- Parses all public functions and their parameter types
- Generates a complete MCP server with type-safe tool implementations
- Creates utility functions for transaction signing and submission
- Produces TypeScript bindings using the official Stellar SDK
Features at a Glance
- TypeScript and Python Server Generation: Supports generating MCP servers in both TypeScript and Python.
- Web Frontend Generation: Optionally generates a Vite web application for browser-based contract interaction.
- PasskeyKit Integration: Seamless integration for smart wallet authentication and transaction signing.
- Robust Transaction Signing: Includes utilities for transaction signing with sequence staleness handling.
- Claude Desktop Integration: Enables AI-assisted interaction with your contracts via Claude Desktop.
Supported Languages
| Language | Framework | Features |
|---|---|---|
| TypeScript | MCP SDK | Full PasskeyKit support, deploy-wallet script |
| Python | FastMCP | Async/await, automatic type conversion |
Key Features
Automatic Tool Generation
Every public function in your Soroban contract becomes an MCP tool:
Contract Function: set_allowlist_wasm(admin: Address, wasm_hash: BytesN<32>)
↓
MCP Tool: set-allowlist-wasm
- Validates inputs with Zod schemas
- Builds unsigned transaction XDR
- Returns XDR for signingTransaction Signing Utilities
Generated servers include robust signing utilities:
- signTransaction() - Signs with keypair, handles sequence staleness
- signAndSendWithPasskey() - Full PasskeyKit smart wallet integration
- submitTransaction() - Submits and polls for results
Web Frontend Generation
Optionally generates a Next.js web application that:
- Connects to your MCP server
- Provides a chat interface for interacting with your contract
- Handles transaction signing via wallet integration
Official Stellar Bindings
Uses stellar contract bindings typescript to generate type-safe contract clients:
// Auto-generated in src/bindings/
export interface Client {
set_allowlist_wasm: (params, options?) => Promise<AssembledTransaction<null>>
deploy_token: (params, options?) => Promise<AssembledTransaction<TokenInfo>>
// ... all contract functions
}Quick Example
# Generate a TypeScript MCP server
stellar mcp generate \
--contract-id CBX7HKQ6WIOYAHS6SLL7Y3MRPTYOSGJTDL6XXYYOTEWEN3PRGK3DSVZG \
--network testnet \
--output my-token-mcp
# Install and build
cd my-token-mcp
pnpm install
pnpm build
# Run the server
pnpm startThe server exposes your contract functions as MCP tools that Claude can use.
Generated Project Structure
my-contract-app/
├── server/ # MCP Server (FastMCP with HTTP transport)
│ ├── src/
│ │ ├── index.ts # MCP server with all tools
│ │ ├── lib/
│ │ │ ├── utils.ts # signTransaction()
│ │ │ ├── passkey.ts # signAndSendWithPasskey()
│ │ │ ├── submit.ts # submitTransaction()
│ │ │ └── transaction.ts # parseTransactionResult()
│ │ ├── tools/ # Contract function handlers
│ │ ├── schemas/ # Zod validation schemas
│ │ └── bindings/ # Official Stellar TypeScript bindings
│ ├── deploy-wallet.ts # PasskeyKit wallet deployment
│ ├── package.json
│ ├── tsconfig.json
│ └── .env.example
└── frontend/ # Vite Web Application
├── src/
│ ├── client/ # React frontend
│ │ ├── components/ # UI components
│ │ │ ├── ChatInterface.tsx # Main chat UI
│ │ │ ├── MessageList.tsx # Chat messages
│ │ │ ├── ChatInput.tsx # Input field
│ │ │ ├── AuthModeSelector.tsx # Auth mode toggle
│ │ │ ├── WalletConnector.tsx # Wallet connection
│ │ │ ├── ContractTools.tsx # Manual tools (legacy)
│ │ │ └── ToolExecutor.tsx # Tool execution (legacy)
│ │ ├── lib/
│ │ │ └── mcp-client.ts # MCP client hook
│ │ ├── App.tsx # Root component
│ │ ├── main.tsx # Entry point
│ │ └── index.css # Tailwind styles
│ └── server/ # Express API backend
│ ├── index.ts # Server entry point
│ └── routes/
│ └── chat.ts # AI chat endpoint
├── package.json
├── vite.config.ts
├── tailwind.config.ts
└── .env.exampleHow It Works
Deployed Contract (on Stellar)
↓
stellar mcp generate --contract-id ...
↓
Fetch Contract Spec (via RPC)
↓
Parse Functions & Types
↓
Generate Code from Templates
↓
Run stellar contract bindings typescript
↓
Complete MCP Server ProjectDocumentation Sections
Last updated on