Chronos

Chronos MCP Server enables AI applications to securely interact with the Stellar blockchain by connecting wallets, listing tokens, querying balances, and transferring funds through a standard MCP interface. It is designed for seamless integration with Claude Desktop and similar tools, turning on-chain capabilities into practical actions for your AI workflows.

How to use

You use Chronos MCP Server by running an MCP client that talks to the server over the MCP protocol. You can connect your Stellar wallet with a secret key, then list tokens held by that wallet, check real-time balances, and initiate transfers to other Stellar wallets. Each action is exposed as an MCP endpoint that your client can invoke with natural language prompts or structured requests.

How to install

Prerequisites you need on your machine are straightforward: install Node.js (version 14 or higher) and npm, have Stellar wallet credentials (secret key), and ensure you have internet access to reach the Stellar network.

# Option 1: Install Chronos MCP Server from npm (recommended)
npm install -g chronos-mcp

# Alternatively, run it directly with npx
npx chronos-mcp@latest

# Option 2: Install from source
git clone https://github.com/yourusername/chronos-mcp.git
cd chronos-mcp
npm install
npm run build
npm link

# Option 3: Using Docker
# Build the image
docker build -t chronos-mcp .
# Run the container
docker run -it --rm chronos-mcp

Configuration and usage notes

Environment variables are used to configure sensitive information such as your Stellar secret key and the network (mainnet or testnet). Create a .env file in the project root and load it at startup.

STELLAR_SECRET_KEY=your_stellar_secret_key
STELLAR_NETWORK=mainnet

Claude Desktop configuration (example)

{
  "mcpServers": {
    "stellar": {
      "command": "npx",
      "args": ["chronos-mcp@latest"],
      "env": {
        "STELLAR_NETWORK": "mainnet",
        "STELLAR_SECRET_KEY": "your_stellar_secret_key"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Docker integration with Claude Desktop

{
  "mcpServers": {
    "stellar": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "--env-file", "/path/to/your/.env", "chronos-mcp"],
      "env": {
        "STELLAR_NETWORK": "mainnet"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Usage endpoints you can invoke

Chronos MCP exposes a set of tools that you can trigger via your MCP client. These are designed to be called from natural language prompts or programmatic requests and do not require you to manage low-level protocol details.

Testing and deployment notes

To verify the server locally, run the test suite or try simple MCP requests against the running server. If you are using Docker, you can test the container with the included client script to ensure end-to-end behavior.

Extending Chronos

To add new on-chain tools, create a new module under the tooling area, implement the tool’s API surface and handlers, export it, and write tests. This keeps Chronos extensible for future Stellar interactions and other MCP-compatible actions.

Security considerations

Keep your Stellar secret key secure. Do not embed secret keys in source control or logs. Use environment variables or secure secret stores in production deployments, and restrict access to the MCP server to trusted clients.

Available tools

connect_wallet

Connect to a Stellar wallet using a secret key to establish a session for subsequent actions.

list_tokens

List all tokens/assets held in the connected Stellar wallet.

get_balances

Retrieve real-time balances for XLM and other assets in the wallet.

transfer_funds

Transfer a specified amount of an asset from your wallet to a destination address.