contacts-mcp

MCP Server for Stellar Smart Contract

This server implements the Model Context Protocol (MCP) and acts as a tool provider for a Soroban smart contract deployed on the Stellar blockchain.

It exposes a standardized MCP interface that allows agents (such as AI models, orchestration frameworks, or automation tools) to discover and invoke the smart contract's available functions safely and consistently.

This server was auto-generated using the Soroban CLI and is optimized for plug-and-play integration into any MCP-compatible environment.

📝 Next steps

1. Install dependencies and build the project:

   cd contacts-mcp
   npm install
   npm run build

2. Add the following configuration to your MCP config file (e.g., in claude_desktop_config.json, mcp.config.json, etc.):

"contacts_mcp": {
  "command": "node",
  "args": [
    "contacts-mcp/build/index.js"
  ],
  "env": {
    "NETWORK": "testnet",
    "NETWORK_PASSPHRASE": "Test SDF Network ; September 2015",
    "RPC_URL": "https://soroban-testnet.stellar.org",
    "CONTRACT_ID": "CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQVU2HHGCYSC"
  }
}

This allows MCP runtimes to run your tool seamlessly.

🧠 What This Server Does Implements the MCP spec to serve Soroban contract methods as tools.

Each method is described via a JSON schema (input/output), allowing agents to introspect and invoke them programmatically.

All logic is executed via Stellar's Soroban smart contract runtime.

⚠️ There are no REST endpoints exposed. Tool interaction happens via MCP-compatible interfaces.

🧪 Exposed Contract Tools The following contract methods are exposed as MCP tools:

• initialize: Initialize the contract with the native XLM token address native_token_addr should be the address of the native XLM Stellar Asset Contract
• add_cont: Add a new contact (account can only add to their own contacts)
• edit_contact: Edit an existing contact (account can only edit their own contacts) Cannot edit contacts that have already been sponsored
• delete_contact: Delete a contact (account can only delete their own contacts) Cannot delete contacts that have already been sponsored
• get_contact: Get a specific contact by alias (account can only read their own contacts)
• get_all_contacts: Get all contacts for the account (account can only read their own contacts)
• get_contacts_count: Get total number of contacts for the account
• spon_coff: Sponsor coffee by sending XLM equivalent to $5 USD to a contact Function will be called through a smart wallet with coffee sponsor policy attached Policy expects args: sponsor (Address), contact_alias (String)
• get_coffee_amount: Get the current coffee sponsorship amount in stroops (XLM)
• is_contact_sponsored_by_user: Check if a contact has been sponsored (public function for frontend use)
• get_sponsored_aliases: Get all sponsored aliases for a user
• is_address_used: Check if an address is already used by any contact for this user (public function for frontend use)
• find_alias_by_address: Find which alias is using a specific address (returns empty string if not found)

Each tool includes parameter validation, metadata, and underlying Soroban invocation logic.

📘 About Model Context Protocol (MCP) MCP enables agents to discover and use tools through a structured protocol — no hardcoded APIs, just standardized tool definitions and execution environments.

Learn more at modelcontextprotocol.io.

This is an auto-generated server. If you need to modify the contract interface, it's recommended to regenerate the server using the Stellar CLI rather than modifying the generated code directly.