stellar-mcp-server

A Model Context Protocol (MCP) server that exposes Stellar blockchain tools directly inside any MCP-compatible AI IDE (Windsurf, Antigravity, Claude Desktop, Cursor, etc.).

Built with the official MCP TypeScript SDK and the Stellar JavaScript SDK.

---

✨ Exposed Tools

Tool	Description
get_account_details	Fetches live balances, sequence number, thresholds, signers, and data entries for any Stellar Testnet account
simulate_soroban_contract	Simulates a Soroban smart contract function call on the Testnet RPC — no real transaction, just fee estimates + decoded return value
generate_soroban_boilerplate	Generates a complete Rust Soroban contract scaffold (Cargo.toml + lib.rs + .cargo/config.toml + test module)

---

📋 Prerequisites

Requirement	Version
Node.js	≥ 18.0.0
npm	≥ 8.0.0

---

🛠 Installation

# 1. Clone the repository
git clone https://github.com/Alhaji-naira/stellar-mcp-server.git
cd stellar-mcp-server

# 2. Install dependencies
npm install

# 3. Build the TypeScript source
npm run build

The compiled server will be at dist/index.js.

---

▶️ Running Locally (manual test)

You can pipe a raw JSON-RPC tools/list call to verify the server responds correctly:

echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' \
  | node dist/index.js

You should see a JSON response listing all three tools. The server emits diagnostics to stderr only (MCP requirement), keeping stdout clean for the protocol.

---

🤖 Registering in Your AI IDE

Windsurf

Add the following to your ~/.codeium/windsurf/mcp_config.json (create it if it doesn't exist):

{
  "mcpServers": {
    "stellar-mcp-server": {
      "command": "node",
      "args": ["/absolute/path/to/stellar-mcp-server/dist/index.js"],
      "transport": "stdio"
    }
  }
}

Reload Windsurf. The Stellar tools will appear in Cascade's tool palette.

Antigravity (Gemini AI)

Open your Antigravity settings panel, go to MCP Servers, and add a new entry:

{
  "name": "stellar-mcp-server",
  "command": "node",
  "args": ["/absolute/path/to/stellar-mcp-server/dist/index.js"],
  "transport": "stdio"
}

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "stellar-mcp-server": {
      "command": "node",
      "args": ["/absolute/path/to/stellar-mcp-server/dist/index.js"]
    }
  }
}

Restart Claude Desktop.

---

🔧 Tool Reference

1. get_account_details

Queries the Stellar Testnet Horizon API for a given account.

Input:

Parameter	Type	Required	Description
account_id	string	✅	The G… Stellar public key to look up

Example prompt to your AI:

"Check the balance of account GAAZI4TCR3TY5OJHCTJC2A4QSY6CJWJH5IAJTGKIN2ER7LBNVKOCCWN on Stellar Testnet."

Example output (abbreviated):

{
  "account_id": "GAAZI4TCR3TY5OJHCTJC2A4QSY6CJWJH5IAJTGKIN2ER7LBNVKOCCWN",
  "network": "Testnet",
  "sequence": "123456789",
  "balances": [
    { "asset": "XLM (native)", "balance": "9999.9999900" }
  ],
  "thresholds": { "low_threshold": 0, "med_threshold": 0, "high_threshold": 0 },
  "signers": [{ "key": "GAAZI4...", "weight": 1, "type": "ed25519_public_key" }]
}

---

2. simulate_soroban_contract

Invokes a Soroban contract function via the Testnet RPC simulation endpoint — no fee is charged, no transaction is broadcast.

Input:

Parameter	Type	Required	Default	Description
contract_id	string	✅	—	C… Soroban contract address
function_name	string	✅	—	Function to call, e.g. hello
args	array	❌	[]	Arguments (strings, numbers, booleans auto-converted to XDR)
source_account	string	❌	Funded Testnet account	G… public key used as simulation source

Example prompt:

"Simulate calling hello with arg World on Soroban contract CABC… on the Testnet."

Example output (abbreviated):

{
  "contract_id": "CABC...",
  "function_name": "hello",
  "simulation": {
    "min_resource_fee": "71652",
    "return_value": ["Hello", "World"],
    "footprint": {
      "read_only": ["AAAA..."],
      "read_write": []
    }
  }
}

---

3. generate_soroban_boilerplate

Returns a complete, compilable Rust Soroban contract scaffold.

Input:

Parameter	Type	Required	Default	Description
contract_name	string	✅	—	CamelCase struct name, e.g. TokenVault
functions	string[]	❌	["hello(env: Env, to: Symbol) -> Vec<Symbol>"]	Function signatures to scaffold
soroban_sdk_version	string	❌	"22.0.0"	soroban-sdk version to pin

Example prompt:

"Generate a Soroban boilerplate for a contract called AetherSwap with functions swap(env: Env, amount: i64) -> i64 and get_price(env: Env) -> i64."

The tool returns formatted Cargo.toml, src/lib.rs, and .cargo/config.toml content ready to paste or write to disk.

---

🗂 Project Structure

stellar-mcp-server/
├── src/
│   ├── index.ts                    # MCP server bootstrap + dispatcher
│   └── tools/
│       ├── registry.ts             # All tool definitions (JSON schemas)
│       ├── getAccountDetails.ts    # Tool 1: Account queries
│       ├── simulateSoroban.ts      # Tool 2: Soroban simulation
│       └── generateBoilerplate.ts  # Tool 3: Rust contract scaffold
├── dist/                           # Compiled JS output (git-ignored)
├── package.json
├── tsconfig.json
└── README.md

---

🌐 Network Configuration

All tools target the Stellar Testnet by default:

Service	URL
Horizon API	https://horizon-testnet.stellar.org
Soroban RPC	https://soroban-testnet.stellar.org
Friendbot (faucet)	https://friendbot.stellar.org/?addr=<G...>

To get a funded Testnet account for testing, visit:

https://friendbot.stellar.org/?addr=<YOUR_PUBLIC_KEY>

---

🔒 Security Notes

• This server operates entirely over local stdio — it does not open any network ports.
• No private keys are stored or required. All operations are read-only or simulation-only.
• The Horizon and Soroban RPC connections use TLS (allowHttp: false).

---

🧑‍💻 Development

# Type-check without emitting
npm run type-check

# Run directly with ts-node (no build step)
npm run dev

# Rebuild after changes
npm run build

---

📄 License

MIT © Alhaji-naira