stellar-mcp

A Model Context Protocol server for the Stellar blockchain. Gives AI coding tools (Cursor, VS Code, Claude Desktop) direct access to Stellar accounts, transactions, Soroban contracts, and the DEX — without writing custom integrations for each one.

---

What this is

MCP is a standard protocol that lets an AI client talk to external tools and data in a uniform way. Instead of building a Cursor plugin + a VS Code plugin + a Claude Desktop plugin all for Stellar, you build one MCP server and every compatible client can use it.

This server exposes Stellar as three MCP primitives:

Primitive	What it is	Examples
Tools	Functions the AI can call	get_account, build_payment_tx, simulate_contract_call
Resources	Read-only context the AI can inspect	stellar://account/{address}, stellar://network/info
Prompts	Reusable task templates	build-payment, debug-soroban

---

Quick start

cp .env.example .env
npm install
npm run dev          # stdio mode — connect Cursor / Claude Desktop

For HTTP mode (hosted / team):

MCP_TRANSPORT=http npm run dev

---

Connecting to Cursor

Add this to your Cursor MCP config (~/.cursor/mcp.json):

{
  "mcpServers": {
    "stellar": {
      "command": "node",
      "args": ["/absolute/path/to/stellar-mcp/dist/index.js"],
      "env": {
        "STELLAR_NETWORK": "testnet"
      }
    }
  }
}

Then run npm run build first, or use tsx for dev:

{
  "command": "npx",
  "args": ["tsx", "/absolute/path/to/stellar-mcp/src/index.ts"]
}

---

Environment variables

Variable	Default	Description
STELLAR_NETWORK	testnet	testnet / mainnet / futurenet
MCP_TRANSPORT	stdio	stdio for local IDE, http for hosted
PORT	3000	HTTP port (ignored in stdio mode)
STELLAR_SECRET_KEY	—	Optional. Only set if you want the server to sign locally.
LOG_LEVEL	info	Pino log level

Never commit a real STELLAR_SECRET_KEY. By default the server produces unsigned XDR and lets you sign with your own wallet.

---

Tools reference

Account tools

Tool	Description
get_account	Account details, balances, flags, sequence
get_transactions	Recent transactions for an account (paginated)
get_transaction	Single transaction by hash
get_fee_stats	Current network fee statistics
friendbot_fund	Fund a testnet/futurenet account (not available on mainnet)

Transaction tools

Tool	Description
build_payment_tx	Build unsigned payment XDR
build_change_trust_tx	Build unsigned trustline XDR
submit_transaction	Submit a signed XDR envelope

Soroban tools

Tool	Description
get_contract_spec	ABI / function signatures for a contract
simulate_contract_call	Dry-run a contract call, get return value + cost

Trading tools

Tool	Description
get_orderbook	Orderbook for a DEX trading pair
find_payment_path	Best path-payment route between two assets

---

Security model

Tools are tiered by sensitivity:

Tier	Tools	Behaviour
read	get_account, get_transactions, etc.	Always auto-allowed
build	build_payment_tx, simulate_contract_call, etc.	Auto-allowed — produces unsigned XDR only
sign	submit_transaction, friendbot_fund	Requires explicit human approval

The server never holds a private key by default. Set STELLAR_SECRET_KEY only if you understand the risk. Secret keys are automatically redacted from logs.

---

Project structure

src/
├── config/         # Network configs and env loading
├── domain/         # Pure TypeScript types (Account, Asset, Transaction, Contract)
├── schemas/        # Zod input/output schemas and validation helpers
├── security/       # Permission tiers, approval gates, secret redaction
├── services/       # Horizon, Soroban RPC, tx-builder, signing, cache
└── server/
    ├── tools/      # MCP tool handlers (accounts, transactions, soroban, trading)
    ├── resources/  # MCP resource handlers (account, contract, network)
    ├── prompts/    # MCP prompt templates (build-payment, debug-soroban)
    ├── transport/  # stdio and HTTP transport setup
    └── index.ts    # Wires everything together

---

Development

npm run dev          # Run with tsx watch (auto-restart on changes)
npm run typecheck    # TypeScript type check
npm test             # Run tests
npm run build        # Compile to dist/

---

Roadmap

• Full Soroban contract spec decoder (WASM parsing)
• Manage offer / DEX order tools
• Path payment transaction builder
• Contract events streaming resource
• Redis cache backend option
• OpenTelemetry tracing