Soroban MCP Server

An MCP (Model Context Protocol) server that gives AI coding agents direct, structured access to Soroban smart contracts and the Stellar network — so agents can build, test, deploy, and inspect contracts without shelling out blindly to the CLI and parsing raw text output.

Demo: (drop a terminal recording or gif here once you have a working build)

Why this exists

AI coding agents are increasingly used to write and debug smart contracts, but today they either guess at CLI syntax or parse unstructured terminal output to decide whether a build succeeded, what a contract's state looks like, or why a deployment failed.

This server exposes those operations as typed, validated MCP tools with structured results and clear error messages — making agent-assisted Soroban development faster and more reliable.

Related MCP server: solagent-mcp

Features

Resources exposed:

• soroban://network/{network}/status — current ledger height and health

• soroban://contract/{id}/abi — contract ABI/spec from on-chain WASM metadata

• soroban://contract/{id}/transactions — recent transaction history

Installation

npm install -g soroban-mcp-server

Or run directly without installing:

npx soroban-mcp-server

Prerequisites:

• Node.js ≥ 20

• stellar-cli on your PATH (required for build_contract and deploy_contract)

Configuration

Add to your MCP client config (e.g. Claude Code's mcp.json):

{
  "mcpServers": {
    "soroban": {
      "command": "npx",
      "args": ["soroban-mcp-server"],
      "env": {
        "STELLAR_NETWORK": "testnet"
      }
    }
  }
}

Usage example

Once connected to your MCP client, an agent can run a full build-test-deploy cycle:

"Build this contract, run the tests, and if they pass, deploy it to testnet and give me the contract ID."

The agent calls build_contract → run_tests → deploy_contract in sequence, using the structured output of each step to decide whether to proceed — without you needing to copy-paste terminal output back and forth.

Tool call examples

Build a contract:

{
  "tool": "build_contract",
  "arguments": { "project_path": "./contracts/my_token" }
}

Run tests with a filter:

{
  "tool": "run_tests",
  "arguments": { "project_path": "./contracts/my_token", "filter": "test_transfer" }
}

Check an account:

{
  "tool": "get_account_info",
  "arguments": { "public_key": "GABC...", "network": "testnet" }
}

Invoke a contract function:

{
  "tool": "invoke_contract",
  "arguments": {
    "contract_id": "CXXX...",
    "function_name": "balance",
    "args": [{ "type": "address", "value": "GABC..." }],
    "network": "testnet"
  }
}

Error handling

Every tool returns structured errors with a code field instead of raw stack traces:

{
  "error": "Insufficient balance to complete the transaction. Fund the account at https://friendbot.stellar.org",
  "code": "INSUFFICIENT_BALANCE"
}

Known error codes: BUILD_FAILED, WASM_NOT_FOUND, INVALID_WASM, NETWORK_TIMEOUT, NETWORK_UNREACHABLE, RPC_ERROR, INVALID_CONTRACT_ID, CONTRACT_NOT_FOUND, CONTRACT_INVOCATION_FAILED, INSUFFICIENT_BALANCE, ACCOUNT_NOT_FOUND, INVALID_PUBLIC_KEY, CLI_NOT_FOUND, CLI_EXECUTION_FAILED, TEST_EXECUTION_FAILED.

Development

git clone https://github.com/your-org/soroban-mcp-server
cd soroban-mcp-server
npm install

npm run typecheck   # TypeScript strict check
npm run lint        # ESLint
npm test            # Unit tests (all network/CLI calls mocked)

# Live testnet integration tests (requires network access)
INTEGRATION=true npm run test:integration

Roadmap

This project is built to grow alongside the Soroban ecosystem. Planned areas of expansion (and a source of ongoing, scoped contribution issues):

• TTL management — bump_contract_ttl tool to extend contract state lifetimes

• Signing support — submit state-changing transactions, not just simulate them

• Additional wallets/signers — Freighter, hardware wallets

• Richer error diagnosis — new failure modes as the protocol evolves

• Prompt templates — common contract patterns (token, escrow, multisig)

• Local devnet support — quickstart Docker integration for offline development

Contributing

See CONTRIBUTING.md. Issues are labeled by scope and complexity — issues tagged good-first-issue are a great place to start.

License

MIT