CLI Agent Template
A terminal agent for Stellar MCP servers. Supports a guided wizard, interactive REPL, and one-shot command mode — useful for developers who want to interact with a Stellar contract directly from the terminal.
Setup
Clone and install
cd stellar-mcp/templates/cli-agent
npm install
cp .env.example .envConfigure environment
Edit .env:
MCP_SERVER_URL=http://localhost:3000/mcp
RPC_URL=https://soroban-testnet.stellar.org
NETWORK_PASSPHRASE="Test SDF Network ; September 2015"
SIGNER_SECRET= # Optional — set to sign write operationsRun
# Guided wizard (default)
npm run dev
# Interactive REPL
npm run dev -- --interactive
# One-shot commands
npm run dev -- list
npm run dev -- call get-adminEnvironment Variables
| Variable | Required | Description |
|---|---|---|
MCP_SERVER_URL | Yes | URL of the MCP server |
RPC_URL | Yes | Soroban RPC endpoint |
NETWORK_PASSPHRASE | Yes | Stellar network passphrase |
SIGNER_SECRET | No | Stellar secret key (S…). If unset, write ops show XDR but do not submit. |
Commands
| Command | Description |
|---|---|
stellar-mcp-cli | Launch guided wizard (select tool → fill args → execute) |
stellar-mcp-cli --interactive | Stay in interactive REPL after each operation |
stellar-mcp-cli list | List all tools on the server |
stellar-mcp-cli list --read-only | Show only read tools |
stellar-mcp-cli list --write-only | Show only write tools |
stellar-mcp-cli list --json | Output tool list as JSON |
stellar-mcp-cli call [tool] | Call a tool (omit name to pick interactively) |
stellar-mcp-cli call [tool] --args <json> | Call with args as a JSON string |
stellar-mcp-cli call [tool] --json | Output result as JSON |
One-Shot Examples
# Read operation
stellar-mcp-cli call get-admin --json
# Write operation with inline key=value args
stellar-mcp-cli call deploy-token --deployer GABC... --config.name MyToken --config.symbol MTK
# Write operation with JSON args
stellar-mcp-cli call deploy-token --args '{"deployer":"GABC...","config":{"name":"MyToken","symbol":"MTK","decimals":7}}'Interactive Mode
stellar-mcp-cli --interactiveStays alive after each operation, letting you chain multiple calls without restarting. Uses @clack/prompts for a polished terminal UI — spinners, selection menus, and text inputs.
JSON Output
Add --json to any command to get machine-readable output — useful for piping into jq or other tools:
stellar-mcp-cli list --json | jq '.[].name'
stellar-mcp-cli call get-admin --json | jq '.data'Without --json, the CLI renders a human-friendly table or formatted output.
Global Installation
Build and install the CLI globally so you can run stellar-mcp-cli from anywhere:
pnpm build
npm install -g .After installation, the stellar-mcp-cli command is available system-wide:
stellar-mcp-cli list
stellar-mcp-cli call get-admin
stellar-mcp-cli --interactiveDuring development, skip the global install and use pnpm dev instead — it runs the CLI directly via tsx.
Build
# Build to dist/
pnpm build
# Run compiled binary
node dist/index.js listCustomization
- Add pre-configured servers — edit
src/constants.tsto add known MCP server URLs - Extend commands — add Commander subcommands in
src/commands/ - Change UI theme —
src/ui.tscontrols chalk colors and spinner styles