Provides structured access to Soroban smart contracts on the Stellar network, including building, testing, deploying, invoking, and inspecting contract state, as well as account and network information.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Soroban MCP Server Deploy my token contract to testnet and give me the contract ID"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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)
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
Tool | Description |
| Builds a Soroban project; returns structured compiler diagnostics (file, line, error code, message) |
| Runs |
| Deploys a compiled |
| Simulates a contract function call; returns result + resource cost (CPU, memory, fee) |
| Reads a contract's persistent/instance/temporary storage entries |
| Returns balance, sequence number, and signers for a Stellar account |
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
npm install -g soroban-mcp-serverOr run directly without installing:
npx soroban-mcp-serverPrerequisites:
Node.js ≥ 20
stellar-cli on your PATH (required for build_contract and deploy_contract)
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"
}
}
}
}Env var | Description | Default |
|
|
|
| Override the default RPC endpoint | network default |
| Path to the Soroban/Stellar CLI binary |
|
|
|
|
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.
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"
}
}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.
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:integrationThis 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
See CONTRIBUTING.md. Issues are labeled by scope and complexity — issues tagged good-first-issue are a great place to start.
Builds a Soroban smart contract project using the Stellar CLI. Returns structured compiler diagnostics (file, line, error code, message) — not raw rustc text.
| Name | Required | Description | Default |
|---|---|---|---|
| network | No | Target network for the build | testnet |
| project_path | Yes | Absolute or relative path to the Soroban contract project directory (contains Cargo.toml) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It adds value by specifying that output is structured compiler diagnostics rather than raw rustc text, which is a meaningful behavioral trait. However, it does not disclose potential side effects such as file system changes, network usage, or permission requirements, leaving notable gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, with the first stating the action and the second clarifying the output format. Every sentence provides essential information, and there is no redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description adequately explains the tool's core purpose and output type. For a build tool with only two parameters and no output schema, it covers the essential usage context. Minor gaps exist (e.g., side effects or success behavior) but the tool is sufficiently described given its complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides full descriptions for both parameters (network enum/default and project_path with Cargo.toml context), achieving 100% coverage. The description does not add additional parameter semantics beyond mentioning the Stellar CLI, so it aligns with the baseline of 3 for fully covered schemas.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Builds' and identifies the resource as 'a Soroban smart contract project using the Stellar CLI.' It clearly distinguishes itself from sibling tools like deploy_contract or invoke_contract by focusing on the build stage. The note about returning structured diagnostics further clarifies its unique purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly state when to use this tool versus its siblings. It implies its role as the build step (before deployment) but lacks direct guidance on prerequisites or exclusion criteria. Users must infer usage from the tool name and sibling context, making it decent yet not fully explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Deploys a compiled .wasm file to testnet or futurenet using the Stellar CLI. Returns the contract ID and transaction hash. Mainnet is intentionally not supported here.
| Name | Required | Description | Default |
|---|---|---|---|
| network | No | Target network (mainnet deployments are not supported by this tool for safety) | testnet |
| wasm_path | Yes | Path to the compiled .wasm file to deploy | |
| ignore_checks | No | Pass --ignore-checks to stellar contract deploy (skip safety warnings) | |
| source_account | Yes | Stellar account secret key or keyname from stellar-cli config to pay for deployment |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description adds some context by noting the returned values and mainnet unsupported, but it omits critical behavioral traits: deployment is a paid, state-changing transaction requiring a funded source account, and it may incur fees. The description does not disclose these side effects or prerequisites, leaving a significant transparency gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, using only two sentences: the first states the primary action, and the second covers return values and an important network restriction. Every word earns its place, and it is front-loaded with the deploy action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 4 parameters and no output schema, the description covers the main action, returns, and network exclusion. However, it lacks explicit prerequisites like 'wasm must be compiled' and 'source account must be funded', which are important for correct invocation. The schema partially compensates, but the description itself is not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides 100% parameter descriptions, so the description does not need to elaborate on parameters. The description's mention of 'using the Stellar CLI' and 'source account' is redundant with the schema, but the schema already covers each parameter's meaning, warranting the baseline score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool deploys a compiled .wasm file to testnet or futurenet, using a specific verb and resource. It distinguishes itself from sibling tools like build_contract or invoke_contract, and also mentions the return values (contract ID and transaction hash).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description indicates the target networks and explicitly excludes mainnet, providing clear usage boundaries. It implies usage after building a wasm file, but does not explicitly name alternatives or when not to use this tool beyond the mainnet exclusion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns balance, sequence number, and signers for a Stellar account. Includes a testnet funding link if the account is not found.
| Name | Required | Description | Default |
|---|---|---|---|
| network | No | Network to query | testnet |
| public_key | Yes | Stellar account public key (starts with G) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavior disclosure. It adds a notable behavior (testnet funding link when account is not found) but omits other potential behaviors like rate limits, error formats, or permission requirements. For a read-only getter, this is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with the primary purpose stated first and the special behavior second. Every word earns its place, making it highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple account query tool with two parameters, the description covers the returned fields and the not-found behavior. Since there is no output schema, listing the return contents is helpful. Minor gaps exist (e.g., network-specific behavior details), but overall it is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with clear explanations for both 'public_key' and 'network'. The tool description adds no new parameter semantics beyond what the schema already provides, resulting in the baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states what the tool returns: balance, sequence number, and signers for a Stellar account. The specific verb 'Returns' combined with the resource and result set clearly distinguishes it from sibling contract operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies usage for retrieving Stellar account information, and the sibling tools are contract-related, so the context is clear. However, it does not explicitly mention alternatives or exclusions, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Reads and returns storage entries (persistent, instance, temporary) for a Soroban contract. Keys and values are decoded to human-readable strings where possible.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of storage entries to return | |
| network | No | Network to query | testnet |
| durability | No | Filter storage entries by durability type (omit to return all) | |
| contract_id | Yes | Contract ID (56-character string starting with C) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It adds useful context by noting keys and values are decoded to human-readable strings where possible. However, it does not mention pagination behavior, network-specific nuances, or potential side effects, leaving gaps given the lack of annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the primary action and resource, and contains no unnecessary details. It is concise and well-structured for a read tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool and complete schema coverage for all parameters, the description adequately covers the tool's purpose and the key behavior of decoding values. It does not describe the return format in detail, but the phrase 'returns storage entries' is sufficient for a straightforward read operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the parameters are fully described in the schema. The description adds no additional parameter-specific meaning beyond what is already in the schema, such as the meaning of limit or network.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reads and returns storage entries for a Soroban contract, using a specific verb and resource. It distinguishes from sibling tools like invoke_contract or deploy_contract by focusing on reading state rather than executing or deploying.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is used to inspect contract storage, but it does not explicitly state when to use it versus alternatives or provide exclusions. No comparison is made with sibling tools such as get_account_info or invoke_contract.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Simulates a Soroban contract function call via RPC. Returns the function result AND simulated resource cost (CPU instructions, memory, min fee). For read-only calls no signing is needed.
| Name | Required | Description | Default |
|---|---|---|---|
| args | No | Arguments to pass to the function. Supported types: number, string, boolean, or objects with {type: "address"|"bytes", value: string} | |
| network | No | Network to invoke on | testnet |
| contract_id | Yes | Contract ID (56-character string starting with C) | |
| function_name | Yes | Name of the contract function to call | |
| source_account | No | Source account public key for simulation (not required for read-only calls). Defaults to a zero-balance account for simulation. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the transparency burden. It discloses key behaviors: simulation via RPC, return of function result and resource costs (CPU, memory, min fee), and signing only needed for non-read-only calls. This goes beyond a simple 'invokes a function' and addresses important operational aspects, though it does not explicitly rule out on-chain side effects or detail error handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the central purpose, and every clause earns its place. It efficiently communicates the simulation nature, return value composition, and a key usage condition without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simulation tool with no output schema, the description sufficiently explains what the tool returns and the signing context. However, it omits prerequisites such as the contract being deployed or the need for a network connection, and it could clarify that simulation does not submit an on-chain transaction. These gaps prevent a perfect score.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the input schema fully documents each parameter. The description adds minimal parameter-specific meaning beyond mentioning signing in the context of read-only calls, which is also covered by the source_account parameter description. At the baseline for full schema coverage, this score is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Simulates') and resource ('Soroban contract function call via RPC'), making the tool's purpose immediately clear. It distinguishes from siblings like deploy_contract or get_contract_state by focusing on function invocation simulation, not deployment or direct state reads.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context that this is a simulation, not actual execution, and notes the signing requirement for read-only calls. However, it offers no explicit comparison to alternatives (e.g., when to use get_contract_state instead) or exclusions, so it slightly misses the highest bar.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Runs the Soroban contract test suite with cargo test. Returns a structured pass/fail report (test name, status, duration, failure message).
| Name | Required | Description | Default |
|---|---|---|---|
| filter | No | Optional test name filter — passed to `cargo test <filter>` | |
| project_path | Yes | Absolute or relative path to the Soroban contract project directory (contains Cargo.toml) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses the return format (pass/fail report with test name, status, duration, failure message), but it does not mention potential side effects like compilation, dependency resolution, or behavior on test failure. With no annotations, the description carries the full burden and leaves some gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that includes the command, purpose, and return value. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple test-runner tool with documented parameters and an explicit return format in the description, the definition is complete. No output schema is needed, and the tool's behavior is adequately scoped.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema fully describes both parameters, including the optional filter. The description adds no additional parameter semantics, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool runs the Soroban contract test suite via `cargo test` and returns a structured report, distinguishing it from build, deploy, invoke, and get-state siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context that the tool is for running tests, but it does not explicitly mention when not to use it or name alternative tools. The purpose and sibling names imply the right usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Each tool targets a distinct resource and action: building, testing, account info, contract state, deployment, and invocation. There is no overlap in purpose, and the descriptions make it easy for an agent to select the right tool.
All tool names follow a consistent verb_noun pattern in snake_case (build_contract, run_tests, get_account_info, get_contract_state, deploy_contract, invoke_contract). This creates a predictable and uniform naming convention.
Six tools is a well-scoped count for a Soroban smart contract development server. Each tool covers a core step in the contract lifecycle without being redundant or overwhelming.
The toolset covers the essential workflow: build, test, deploy, invoke, inspect state, and manage account access. While additional tools could be added (e.g., listing contracts), the existing set is sufficient for common development tasks and has no obvious dead ends.
Native Solana staking for AI agents. 26 MCP tools, one-shot signing, webhooks.
MCP-first toolbox for agents: KV storage, auth, queue, and utility tools. Free in early access.
Pay-per-use tool marketplace for AI agents. Search, price-check, and call APIs via MCP.
Your org's AI agents, tasks, runs, search, and brain files as MCP tools and resources.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/firstJOASH/soroban-mcp-server'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
