StellarMCP
Provides tools for querying Stellar blockchain data, including accounts, DEX orderbooks, transactions, trade history, asset metadata, and network status, with x402 micropayments settled on Stellar.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@StellarMCP what's the XLM price on Stellar?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
StellarMCP
Data Merchant for the Agent Economy
MCP server giving AI agents access to Stellar blockchain data — accounts, DEX orderbooks, transactions, trade history, asset metadata, and network status — with every tool call monetized via x402 micropayments settled on Stellar.
Built for the Stellar Hacks: Agents hackathon.
Features
17 MCP tools querying Stellar Horizon REST + Soroban contracts (SEP-41 tokens)
Multi-oracle price aggregation with median computation and source attribution across SDEX and Reflector
PriceService with VWAP, OHLC history, and oracle abstraction layer
x402 micropayments on Stellar — agents pay per call in USDC
Triple transport — stdio for local MCP clients, HTTP REST for x402-gated access, MCP-over-HTTP at
/mcp(StreamableHTTPServerTransport with stateful sessions) for remote MCP clients132 tests — 106 unit + 26 live testnet integration
Production-ready — multi-stage Dockerfile, mainnet auto-defaults, enriched
/health, self-service/docspage with embedded Swagger UIEarn/spend demo + trading strategies — SMA crossover, cross-pair arbitrage, real x402 settlement loop
OpenClaw compatible — permissionless agent discovery via
GET /skill.mdZero
@stellar/stellar-sdkin production bundle — rawfetchto Horizon, dynamic import only for Soroban contract simulation
Related MCP server: Nexus MCP
Quick Start
MCP Client (stdio — free, local)
npx stellar-mcp-x402Or add to your MCP client config:
{
"mcpServers": {
"stellarmcp": {
"command": "npx",
"args": ["stellar-mcp-x402"],
"env": {
"STELLAR_NETWORK": "testnet"
}
}
}
}MCP Client (HTTP — remote)
Connect to a running StellarMCP HTTP server from any MCP client that supports the StreamableHTTP transport. Point your client at http://<host>:4021/mcp — the same McpServer instance with all 17 tools is shared between the stdio and HTTP transports.
# Start the HTTP server (also serves /mcp)
TRANSPORT=http pnpm start
# MCP clients connect via POST/GET/DELETE http://localhost:4021/mcp
# Stateful sessions are tracked via the mcp-session-id header.The /mcp endpoint is free (not x402-gated). Per-tool x402 gating applies to the REST endpoints under /tools/*.
HTTP Server (x402-monetized)
git clone https://github.com/siriuslattice/stellarmcp.git
cd stellarmcp
pnpm install
cp .env.example .env
# Edit .env with your Stellar testnet wallet and OZ facilitator key
TRANSPORT=http pnpm startThen query:
# Free endpoint
curl http://localhost:4021/tools/getNetworkStatus
# Paid endpoint (requires x402 payment header)
curl http://localhost:4021/tools/getAccount?accountId=GAAZI4TCR3TY5OJHCTJC2A4QSY6CJWJH5IAJTGKIN2ER7LBNVKOCCWN7
# View pricing
curl http://localhost:4021/pricing
# Connect an MCP client via MCP-over-HTTP
# POST http://localhost:4021/mcp (JSON-RPC)
# GET http://localhost:4021/mcp (SSE stream)Tools
Horizon Data Tools
Tool | Description | Price |
| Account balances, thresholds, signers | $0.001 |
| Recent transactions for an account | $0.001 |
| Recent payments for an account | $0.001 |
| DEX orderbook with spread and midprice | $0.002 |
| OHLC candle data for a trading pair | $0.002 |
| Asset metadata, supply, flags | $0.001 |
| Network health and protocol version | Free |
| Ledger details by sequence number | $0.001 |
| Account effects (balance changes, trades, etc.) | $0.001 |
| Open DEX offers for an account | $0.001 |
| All operations for an account | $0.001 |
| Stellar AMM liquidity pools | $0.002 |
| Claimable balances by claimant or asset | $0.001 |
Price Tools
Tool | Description | Price |
| Current price for any Stellar asset pair with multi-oracle aggregation (median + | $0.002 |
| OHLC price history with VWAP | $0.002 |
| Volume-weighted average price | $0.002 |
The price tools are powered by PriceService, which aggregates data from the Stellar SDEX via trade aggregations. A PriceAggregator layer combines multiple oracle sources (currently SdexOracle + ReflectorOracle stub) and returns a median price along with a sources[] array containing {name, price, timestamp} entries for full attribution. Additional oracles (Chainlink, Redstone, Band) plug into the same OracleProvider interface.
Soroban Token Tools
Tool | Description | Price |
| SEP-41 token metadata (symbol, name, decimals) and optional balance lookup | $0.002 |
Requires SOROBAN_RPC_URL to be configured. Uses Soroban contract simulation (read-only, no fees).
Asset Format
Type | Format | Example |
Native |
|
|
Classic |
|
|
Agent Demo
The earn/spend loop demonstrates the full agent economy:
# Terminal 1: Start the x402 HTTP server (earn side)
TRANSPORT=http pnpm start
# Terminal 2: Start a mock external x402 service (spend side)
pnpm demo:service
# Terminal 3: Run the agent demo
pnpm demoThe agent:
Earns USDC by receiving x402 payments from clients querying Stellar data
Spends USDC by paying external x402 services to enrich its outputs
Development
pnpm install
pnpm typecheck # Type check (zero errors required)
pnpm test # Run unit tests
pnpm build # Build for production
pnpm inspect # Open MCP Inspector at localhost:6274Architecture
stdio transport ──> McpServer ──> 17 tools ──> HorizonClient ──> Stellar Horizon REST API
│ │
│ ├── PriceService
HTTP transport ──> Express ──┬── /tools/* (REST + x402)
├── /mcp (StreamableHTTPServerTransport)
└── /pricing, /health, /skill.md (free)
│
└── PriceAggregator → [SdexOracle, ReflectorOracle]Both the stdio and HTTP transports share the same McpServer instance with all 17 tools registered. The /mcp endpoint is a MCP-over-HTTP bridge (POST/GET/DELETE) using StreamableHTTPServerTransport with stateful sessions tracked via the mcp-session-id header — giving remote MCP clients the full protocol (tools, resources, prompts) without stdio.
The PriceService sits on top of HorizonClient and provides normalized price data (current price, OHLC history, VWAP). The PriceAggregator layer fans out queries to multiple OracleProviders (SdexOracle + ReflectorOracle today) and computes a median with per-source attribution. Additional oracles (Chainlink, Redstone) plug in via the same interface.
Tech Stack
TypeScript with strict mode
Node.js 22+
MCP SDK (
@modelcontextprotocol/sdk)x402 (
@x402/express,@x402/stellar,@x402/core)Express 4 with CORS and rate limiting
Vitest for testing
tsup for bundling
Environment Variables
See .env.example for all options.
Variable | Required | Default | Description |
| No |
|
|
| No |
| Horizon API URL |
| No |
|
|
| HTTP mode | — | Your Stellar address for receiving payments |
| HTTP mode | — | OpenZeppelin x402 facilitator URL |
| HTTP mode | — | OpenZeppelin facilitator API key |
| No |
| HTTP server port |
| No |
|
|
| No | — | Soroban RPC URL (used by ReflectorOracle and future SEP-41 support) |
| No | — | Reflector oracle contract ID on Stellar (enables ReflectorOracle in PriceAggregator) |
Documentation
Architecture — component map, data flow, key design decisions (8 Mermaid diagrams)
Metrics — verifiable current state evidence (every metric reproducible from this repo)
Deployment — production deployment guide (Docker, PM2, systemd, nginx, Caddy, monitoring, security)
MCP Registry submission — guide for publishing to the official MCP Registry
x402 Bazaar registration — guide for registering on the Coinbase CDP x402 Bazaar
OpenAPI spec — full OpenAPI 3.1 spec for all 22 endpoints
Live
/docspage — when the HTTP server is running, visithttp://localhost:4021/docsfor an embedded Swagger UI
License
MIT
Available Tools
17 toolsgetAccountA
Get Stellar account details including balances, thresholds, and signers
Inputs: accountId (required).
getAssetInfoA
Get metadata for a Stellar asset including supply, accounts, and flags
Inputs: assetCode (required), assetIssuer.
getClaimableBalancesC
Get claimable balances for a Stellar account
Inputs: asset, limit, claimant.
getEffectsC
Get recent effects for a Stellar account
Inputs: accountId (required), limit.
getLedgerB
Get details of a specific Stellar ledger by sequence number
Inputs: sequence.
getLiquidityPoolsC
Get Stellar liquidity pools
Inputs: limit, account.
getNetworkStatusA
Get Stellar network status (free — no payment required)
Inputs: no named parameters.
getOffersA
Get open DEX offers for a Stellar account
Inputs: accountId (required), limit.
getOperationsB
Get recent operations for a Stellar account
Inputs: accountId (required), limit.
getOrderbookA
Get Stellar DEX orderbook for an asset pair with spread and midprice
Inputs: buyingAsset (required), sellingAsset (required), limit.
getPaymentsC
Get recent payments for a Stellar account
Inputs: accountId (required), limit.
getPriceB
Get the current price for a Stellar asset pair from SDEX orderbook or recent trades
Inputs: baseAsset (required), counterAsset (required).
getPriceHistoryA
Get OHLC price history for a Stellar asset pair from SDEX trade aggregations
Inputs: baseAsset (required), counterAsset (required), limit, resolution.
getSorobanTokenInfoA
Get SEP-41 Soroban token metadata (symbol, name, decimals) and optionally a balance for a Stellar account. Requires SOROBAN_RPC_URL to be configured.
Inputs: contractId (required), accountId.
getTradeAggregationsB
Get OHLC trade aggregation data for a Stellar DEX asset pair
Inputs: baseAsset (required), counterAsset (required), limit, resolution.
getTransactionsB
Get recent transactions for a Stellar account
Inputs: accountId (required), limit.
getVWAPA
Get volume-weighted average price for a Stellar asset pair from SDEX trade aggregations
Inputs: baseAsset (required), counterAsset (required), limit, resolution.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 17 tools
Most tools are clearly distinct, but getTradeAggregations and getPriceHistory both provide OHLC data from SDEX trade aggregations, making their boundary unclear. getPrice and getOrderbook also overlap around price discovery, so an agent could easily select the wrong tool for a price query.
All tools follow a consistent camelCase verb_noun pattern using 'get' plus the resource name, such as getAccount, getLedger, and getLiquidityPools. There is no mixing of naming conventions or ambiguous verb styles.
At 17 tools, the server sits in the 'heavy' range, though each tool does target a distinct Stellar data resource. The count is defensible for a broad read-only Stellar data API but is slightly more than the typical well-scoped server.
The server covers a wide range of Stellar data resources: accounts, transactions, payments, operations, effects, ledgers, assets, DEX orderbooks, trades, offers, liquidity pools, claimable balances, network status, and Soroban token info. Minor gaps exist, such as fetching a single transaction by hash or listing ledgers, but most core read-only workflows are covered.
Maintenance
Related MCP Connectors
MCP server connecting AI agents to non-custodial staking data across 130+ networks.
Monetize any MCP server: x402 paywall, pay-per-call billing in USDC on Base, agent marketplace.
Paid deterministic utilities and automation services for AI agents via MCP and x402.
Pay-per-call MCP tools run by autonomous AI agents, each call paid with x402 in USDC.
Related MCP Servers
- FlicenseAqualityNot gradedmaintenanceAn MCP server that transforms SKILL.md files into executable tools for AI agents, allowing them to discover and pay for services via the x402 protocol. It supports automatic payments on Stellar and EVM networks, enabling seamless integration of premium API skills.65 npm1-
- AlicenseNot gradedqualityDmaintenanceMCP server with X402 payment integration, enabling AI agents to access paid tools like weather, web search, and image generation with crypto payments via MetaMask on Base network.MIT
- AlicenseNot gradedqualityDmaintenanceAn MCP server that provides DeFi data tools (crypto prices, whale concentration, funding rates) for AI agents via the x402 protocol.1MIT
- FlicenseNot gradedqualityDmaintenanceAn MCP server for AI agents to purchase resources via Stellar testnet USDC, handling quotes, purchase URLs, and merchant receipts.-