# stellar-pulse-mcp

Read-only **Stellar analytics** for AI assistants, over the [Model Context Protocol](https://modelcontextprotocol.io).
Ask Claude (or any MCP client) about network health and fees, asset quality, DEX order books, accounts and DeFi on
Stellar, and get structured answers from public APIs. **No API keys. No signing. No transactions.**

Existing Stellar MCP servers focus on building and sending transactions or developing Soroban contracts. This one is
for the other half of the job: *understanding what is happening* on the network, and spotting what is not trustworthy.

| Tool | What it answers |
| :--- | :--- |
| `stellar_network_status` | Latest ledger (age, transactions, failure rate, protocol version, base reserve) and fee levels |
| `stellar_asset` | Price, supply, holders, 7d volume, rating and **look-alike warnings** for an asset (`XLM`, `USDC` or `CODE-ISSUER`) |
| `stellar_top_assets` | Most active assets by volume, trades, payments, holders or StellarExpert rating |
| `stellar_orderbook` | SDEX order book for a pair: best bid/ask, mid, spread, depth within 1% and 5% |
| `stellar_account` | Balances, **spendable XLM** after reserve and open offers, signers, thresholds, clawback flag, recent payments |
| `stellar_defi` | Stellar DeFi from DefiLlama: TVL, rank among chains, leading protocols, TVL by category |

Example prompts:

- "Is the Stellar network congested right now, and what are fees doing?"
- "Is this USDC the real one?" (give it `USDC-G...`; it checks the issuer, domain, holders and rating)
- "How deep is the XLM/USDC book on the SDEX, and what is the spread?"
- "How much XLM can this account actually spend?"
- "What are the biggest DeFi protocols on Stellar and which are growing?"

## Why the safety details matter

- **Many assets share a code.** Anyone can issue a token called `USDC`. `stellar_asset` picks the most traded one when
  you give only a code, tells you how many others use the same code, and flags issuers with no verified home domain,
  a low rating, very few holders or no volume.
- **Secret keys are refused.** A value starting with `S` is rejected immediately, before any network call, and never
  echoed back. Public addresses (starting with `G`) are all this server ever needs.
- **Spendable XLM is computed, not guessed**: `(2 + subentries + sponsoring - sponsored) x base reserve`, minus XLM
  locked in open offers, with the reserve read from the latest ledger.

## Install

Requires Node.js 20 or newer. The quickest way is `npx`, no clone needed:

### Claude Code

```bash
claude mcp add stellar-pulse -- npx -y stellar-pulse-mcp
```

On Windows, run it from `cmd` (PowerShell swallows the `--`) and wrap `npx` so Claude Code can start it:

```bat
claude mcp add stellar-pulse -- cmd /c npx -y stellar-pulse-mcp
```

Add `-s user` to make it available in every folder, not just the current project.

### Claude Desktop

```json
{
  "mcpServers": {
    "stellar-pulse": {
      "command": "npx",
      "args": ["-y", "stellar-pulse-mcp"]
    }
  }
}
```

On Windows use `"command": "cmd"` with `"args": ["/c", "npx", "-y", "stellar-pulse-mcp"]`.

Published on [npm](https://www.npmjs.com/package/stellar-pulse-mcp) and in the official MCP Registry as
`io.github.markankamaransheogarat-sys/stellar-pulse-mcp`.

To run it from source instead:

```bash
git clone https://github.com/markankamaransheogarat-sys/stellar-pulse-mcp.git
cd stellar-pulse-mcp
npm install
npm run build
node dist/index.js
```

## Details

- **Data sources:** [Horizon](https://developers.stellar.org/docs/data/apis/horizon) (ledgers, fees, accounts,
  order books), [StellarExpert](https://stellar.expert/openapi.html) (asset statistics and ratings) and
  [DefiLlama](https://defillama.com/docs/api) (TVL). Mainnet only.
- **Units:** Horizon amounts are decimal units; StellarExpert supplies and volumes come in stroops and are converted
  (1 XLM = 10,000,000 stroops).
- **One source down is not a failure.** Where a tool combines sources, it answers from what is reachable and lists
  what failed in an `errors` field.
- **Caching:** 3 to 4 seconds for ledger-level data, 60 seconds for StellarExpert, 5 minutes for DefiLlama, so free
  tiers are not hammered. Simultaneous identical requests share one call.
- **Depth** counts the best 100 levels per side of the SDEX book. Liquidity pools and Soroban DEXes are not included.
- **Not financial advice.** Snapshots of public data, seconds to minutes old.

## Development

```bash
npm run typecheck   # tsc --noEmit over src and tests
npm test            # vitest, all HTTP mocked
npm run build       # compile to dist/
npm run smoke       # live check against the real APIs (needs a build first)
```

`src/sources/*` talk to one API each, `src/tools/*` hold the logic and register one MCP tool each, `src/stellar.ts`
validates account ids and asset references, `src/http.ts` is the shared client (timeout, bounded retries, TTL cache).

A sibling project, [crypto-pulse-mcp](https://github.com/markankamaransheogarat-sys/crypto-pulse-mcp), does the same
for cross-exchange prices, perpetual funding and stablecoin flows.

## License

MIT