StellarMCP

MCP server for Stellar: accounts, payments, XDR, Horizon/Soroban RPC, AMM liquidity, SEP anchors, and Soroban (simulate, invoke, events, deploy, contract state). Intended for agents and IDE integrations (Cursor, Claude Desktop, etc.) with strict validation, normalized errors, and redacted _debug fields.

All tools (names, descriptions, parameters): docs/TOOLS.md — auto-generated from the same tools/list your MCP client sees; attach or paste it when asking an agent how to use this server.

Requirements: Node.js ≥ 20. · Source: github.com/JulioMCruz/Stellar-mcp

Table of contents

• Quick start

• Sanity check (first call)

• Run the server

• Connect your MCP client

• Environment variables

• Security

• Tools reference

• Example tool calls

• Tools reference (detailed — docs/TOOLS.md)

• Soroban contract MCP generator

• Troubleshooting

• Development & testing

Related MCP server: verdigraph

Quick start

From a clone (this repository)

git clone https://github.com/JulioMCruz/Stellar-mcp.git
cd Stellar-mcp
npm install
npm run build

Run the server (see Run the server), then connect your MCP client.

From npm

Package on npm: @juliomcruz/stellarmcp (scoped package, when published).

The published tarball includes build/src, templates/, generator inputs (src/lib/errors.ts, redact.ts), .env.example, and docs — enough to run the server and stellarmcp-generate without cloning.

npm install @juliomcruz/stellarmcp
npx stellarmcp
# or: npx @juliomcruz/stellarmcp

• Env template: node_modules/@juliomcruz/stellarmcp/.env.example → copy to your project as .env if needed.

• MCP stdio when the package is a dependency (example): "args": ["${workspaceFolder}/node_modules/@juliomcruz/stellarmcp/build/src/index.js"].

Prefer GitHub if you are developing or patching this repository (clone).

Sanity check (first call)

Use this to confirm wiring before deeper integration:

1. HTTP mode: with MCP_TRANSPORT=http-sse running, open GET /health (expect JSON with network, horizonReachable, rpcReachable).

2. Any MCP host: call tool stellar_get_fee_stats with {}. Expect fields like baseFee, p99, recommendedFee (see Example tool calls).

If that works, Horizon is reachable and the server is usable for read-only tools without a secret key.

For every tool name and argument shape, use docs/TOOLS.md (or your host’s MCP tool picker).

Run the server

After npm run build, the entrypoint is build/src/index.js.

Connect your MCP client

stdio (recommended locally)

Point your host at Node and the built entrypoint. Example shape (paths must be absolute or use your editor’s variable such as ${workspaceFolder}):

{
  "mcpServers": {
    "stellarmcp": {
      "type": "stdio",
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/stellarmcp/build/src/index.js"],
      "env": {
        "MCP_TRANSPORT": "stdio",
        "STELLAR_NETWORK": "testnet"
      }
    }
  }
}

• Cursor: project config ~/.cursor/mcp.json or .cursor/mcp.json — see Cursor MCP docs (interpolation: ${workspaceFolder}, ${env:VAR}).

• Claude Desktop: claude_desktop_config.json under the same mcpServers pattern.

• Optional: set "envFile": "${workspaceFolder}/.env" (stdio only in Cursor) to load secrets from a local .env without committing it.

Never commit real STELLAR_SECRET_KEY or anchor tokens.

HTTP / SSE

1. Start the server with MCP_TRANSPORT=http-sse and choose PORT.

2. In the client, register the remote server, for example:

{
  "mcpServers": {
    "stellarmcp": {
      "url": "http://localhost:3000/mcp"
    }
  }
}

3. Verify GET http://localhost:3000/health before debugging MCP calls.

When binding HTTP/SSE to anything other than loopback, set MCP_HTTP_AUTH_TOKEN and send MCP requests with Authorization: Bearer <token>. The server refuses non-loopback HTTP/SSE startup without that token.

Environment variables

Authoritative template: copy [.env.example](./.env.example) to .env and edit.

Custom Horizon/RPC/SEP-38 URLs must use https and non-private hosts; unknown hosts require STELLAR_ALLOWED_HOSTS.

Security

1. Secrets: Treat STELLAR_SECRET_KEY like production key material. Prefer env or envFile; never commit secrets; restrict file permissions on .env.

2. Auto-sign policy (write tools: payments, trustlines, liquidity, set_options, fee bump, Soroban invoke/deploy, relevant SEP flows):

   • safe (recommended): unsigned mode — write tools return unsigned XDR for external signing when applicable.

   • guarded: auto-sign enabled only with STELLAR_AUTO_SIGN_LIMIT > 0 and USDC-based valuation rules; fails closed when value cannot be bounded.

   • expert: unlimited auto-sign — use only with full awareness of risk.

3. Network exposure: Keep HTTP/SSE bound to 127.0.0.1 unless you have a reason to expose it. If you expose HTTP/SSE, set MCP_HTTP_AUTH_TOKEN, use TLS in front, sane firewall rules, and review MCP_HTTP_*. MCP_HTTP_TRUST_PROXY=true only behind a trusted proxy that sets X-Forwarded-For correctly.

4. Allowlists: Use STELLAR_ALLOWED_HOSTS and STELLAR_TRUSTED_ANCHOR_DOMAINS when pointing at non-default infrastructure or anchors.

5. Read-only deployments: Omit STELLAR_SECRET_KEY; read and simulate tools still work; writes yield unsigned payloads or explicit errors.

Tools reference

Full detail for agents (every tool, descriptions, parameter tables from live tools/list): docs/TOOLS.md — auto-generated; refresh with npm run docs:tools after you change tools.

Summary below: Read = no transaction submission by this server; Write = may build/submit transactions, call Friendbot, or initiate anchor flows.

Accounts & history

Payments & fees

Assets & AMM

Network

XDR

Historical meta (Horizon-first, Soroban RPC fallback, bounded XDR)

SEP / anchors

Soroban

Example tool calls

JSON shapes are illustrative; your MCP host sends tools/call with name + arguments.

Fee stats (testnet)

{ "name": "stellar_get_fee_stats", "arguments": {} }

XDR: list types → schema → encode

{ "name": "stellar_xdr_types", "arguments": { "prefix": "Transaction" } }

{ "name": "stellar_xdr_json_schema", "arguments": { "type": "TransactionEnvelope" } }

{ "name": "stellar_xdr_encode", "arguments": { "type": "TransactionEnvelope", "json": "<JSON string>" } }

{ "name": "stellar_xdr_guess", "arguments": { "xdr": "<base64>" } }

{ "name": "stellar_decode_xdr", "arguments": { "xdr": "<base64 classic transaction XDR>" } }

Historical meta

{ "name": "stellar_get_ledger_meta", "arguments": { "ledgerSequence": 123456, "maxXdrCharsPerField": 8192 } }

{
  "name": "stellar_get_transaction_meta",
  "arguments": {
    "transactionHash": "<64-char hex>",
    "operationIndex": 0,
    "maxXdrCharsPerField": 8192
  }
}

For full argument schemas, use your client’s tool list / schema UI or inspect Zod definitions under src/tools/.

Soroban contract MCP generator

Generate a standalone Node MCP package (stdio) from a deployed contract’s WASM (contractspecv0) or from a spec JSON manifest.

Inputs

1. WASM — Spec.fromWasm reads the custom section (same idea as @stellar/stellar-sdk contract specs).

2. Spec JSON — format stellarmcp-contract-spec-v1 with entries[] of base64 ScSpecEntry XDR values.

CLI (from this repo after npm run build)

node build/src/generator/cli.js --input path/to/contract.wasm --out ./my-contract-mcp --name my-contract-mcp --alias mytoken
# or
node build/src/generator/cli.js --input path/to/spec.json --out ./my-contract-mcp --name my-contract-mcp --alias mytoken

Published installs: stellarmcp-generate (same flags).

Then in the output directory:

npm install && npm run build
STELLAR_CONTRACT_ID=C... STELLAR_NETWORK=testnet node build/src/index.js

Non-goals (current generator)

• No generated HTTP/SSE transport in the scaffold (stdio only).

• Exotic spec shapes may emit loose Zod at the edges; simulation on RPC remains authoritative.

• Multi-contract workspaces / auto-publish are out of scope for the generator CLI.

Versioning artifacts in generated code: GENERATOR_ARTIFACT_VERSION, SPEC_FINGERPRINT, etc. — regenerate when upgrading stellarmcp or changing the contract interface.

Troubleshooting

Development & testing

npm run typecheck
npm run test             # build + unit tests + docs/TOOLS.md drift check
npm run docs:tools       # regenerate docs/TOOLS.md after changing MCP tools
npm run verify:phase:c   # full maintainer gate (see package.json)

Useful smokes:

• npm run smoke:phase1 — config + stdio + HTTP wiring.

• npm run smoke:testnet:readonly — real testnet reads + Soroban via MCP stdio (no secret key).

• npm run smoke:tier1:friendbot — Friendbot-funded flows on testnet.

Inspired by stellarskills

Knowledge layer: stellarskills. Execution layer: StellarMCP.

License: MIT (see repository).