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

Related MCP server: StellarMCP

📋 Prerequisites

🛠 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:

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:

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:

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:

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