Skip to main content
Glama

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 clients

  • 132 tests — 106 unit + 26 live testnet integration

  • Production-ready — multi-stage Dockerfile, mainnet auto-defaults, enriched /health, self-service /docs page with embedded Swagger UI

  • Earn/spend demo + trading strategies — SMA crossover, cross-pair arbitrage, real x402 settlement loop

  • OpenClaw compatible — permissionless agent discovery via GET /skill.md

  • Zero @stellar/stellar-sdk in production bundle — raw fetch to Horizon, dynamic import only for Soroban contract simulation

Related MCP server: Nexus MCP

Quick Start

MCP Client (stdio — free, local)

npx stellar-mcp-x402

Or 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 start

Then 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

getAccount

Account balances, thresholds, signers

$0.001

getTransactions

Recent transactions for an account

$0.001

getPayments

Recent payments for an account

$0.001

getOrderbook

DEX orderbook with spread and midprice

$0.002

getTradeAggregations

OHLC candle data for a trading pair

$0.002

getAssetInfo

Asset metadata, supply, flags

$0.001

getNetworkStatus

Network health and protocol version

Free

getLedger

Ledger details by sequence number

$0.001

getEffects

Account effects (balance changes, trades, etc.)

$0.001

getOffers

Open DEX offers for an account

$0.001

getOperations

All operations for an account

$0.001

getLiquidityPools

Stellar AMM liquidity pools

$0.002

getClaimableBalances

Claimable balances by claimant or asset

$0.001

Price Tools

Tool

Description

Price

getPrice

Current price for any Stellar asset pair with multi-oracle aggregation (median + sources[] attribution)

$0.002

getPriceHistory

OHLC price history with VWAP

$0.002

getVWAP

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

getSorobanTokenInfo

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

XLM

XLM

Classic

CODE:ISSUER

USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN

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 demo

The agent:

  1. Earns USDC by receiving x402 payments from clients querying Stellar data

  2. 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:6274

Architecture

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

STELLAR_NETWORK

No

testnet

testnet or pubnet

HORIZON_URL

No

https://horizon-testnet.stellar.org

Horizon API URL

TRANSPORT

No

stdio

stdio or http

STELLAR_PAYEE_ADDRESS

HTTP mode

—

Your Stellar address for receiving payments

OZ_FACILITATOR_URL

HTTP mode

—

OpenZeppelin x402 facilitator URL

OZ_API_KEY

HTTP mode

—

OpenZeppelin facilitator API key

PORT

No

4021

HTTP server port

LOG_LEVEL

No

info

debug, info, warn, error

SOROBAN_RPC_URL

No

—

Soroban RPC URL (used by ReflectorOracle and future SEP-41 support)

REFLECTOR_CONTRACT_ID

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 /docs page — when the HTTP server is running, visit http://localhost:4021/docs for an embedded Swagger UI

License

MIT

Available Tools

17 tools
getAccountA

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

    B3.3/5.0

    Scored across 17 tools

    Disambiguation2/5

    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.

    Naming Consistency5/5

    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.

    Tool Count3/5

    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.

    Completeness4/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      A
      quality
      Not graded
      maintenance
      An 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.
      6
      5 npm
      1
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      An MCP server that provides DeFi data tools (crypto prices, whale concentration, funding rates) for AI agents via the x402 protocol.
      1
      MIT