stellar-expert-mcp

A Model Context Protocol server that gives an AI agent read-only access to the stellar.expert Explorer API — accounts, assets, ledgers, transactions, trades, price candles, markets, liquidity pools, offers, Soroban contracts (including WASM download), the well-known-address directory, and a live ledger stream, on Stellar mainnet or testnet.

It acts as key-holding middleware: the server reads your stellar.expert API key from its own environment and injects it into every upstream request. The connecting agent never sees or supplies the key — it just calls tools. This unlocks the paid endpoints (list_transactions, get_transaction, asset_candles, market_candles) behind your subscription without exposing the credential to the model.

The upstream client and endpoint map are ported from stellar-expert-skills, where every path, parameter, and quirk was verified against the live API. 59 tools across the full surface.

agent ──(MCP tools, no key)──▶ stellar-expert-mcp ──(Bearer key, server-held)──▶ stellar.expert

Install & configure

Requires Python ≥ 3.10 (or use Docker, below).

pip install git+https://github.com/rawritude/stellar-expert-mcp

Claude Code

claude mcp add stellar-expert \
  -e STELLAR_EXPERT_API_KEY=your_key_here \
  -e STELLAR_NETWORK=public \
  -- stellar-expert-mcp

Claude Desktop / any MCP client (JSON config)

{
  "mcpServers": {
    "stellar-expert": {
      "command": "stellar-expert-mcp",
      "env": {
        "STELLAR_EXPERT_API_KEY": "your_key_here",
        "STELLAR_NETWORK": "public"
      }
    }
  }
}

The server speaks MCP over stdio. The API key stays in the client's env block (or your shell / a secrets manager) — it is never passed through the model.

API key

Most endpoints are public and work with no key. A key does two things:

1. raises rate limits, and
2. unlocks the paid endpoints (list_transactions, get_transaction, asset_candles, market_candles), which return HTTP 402 without a valid stellar.expert subscription key.

Set it via STELLAR_EXPERT_API_KEY. STELLAR_NETWORK selects public (default) or testnet.

Docker

The image never bakes in the key — pass it at run time:

docker build -t rawritude/stellar-expert-mcp .
docker run --rm -i \
  -e STELLAR_EXPERT_API_KEY=your_key_here \
  -e STELLAR_NETWORK=public \
  rawritude/stellar-expert-mcp

MCP client config pointing at the container:

{
  "mcpServers": {
    "stellar-expert": {
      "command": "docker",
      "args": ["run", "--rm", "-i",
               "-e", "STELLAR_EXPERT_API_KEY",
               "-e", "STELLAR_NETWORK",
               "rawritude/stellar-expert-mcp"],
      "env": { "STELLAR_EXPERT_API_KEY": "your_key_here", "STELLAR_NETWORK": "public" }
    }
  }
}

Tools

59 tools grouped by resource. A few highlights:

Run the server and call tools/list for the full set with schemas.

Development

git clone https://github.com/rawritude/stellar-expert-mcp
cd stellar-expert-mcp
pip install -e ".[dev]"
cp .env.example .env          # optional: add a key for the live tests

python -m pytest -m "not live" -q   # offline (what CI runs)
python -m pytest -q                 # + live integration against the real API

License

MIT © rawritude