xian-mcp-server

xian-mcp-server is a Model Context Protocol (MCP) server that exposes the Xian blockchain to AI assistants and HTTP clients. It wraps xian-tech-py to offer wallet management, transactions, smart-contract reads and writes, indexed BDS reads, shielded wallet sync, token discovery, DEX trading, and cryptographic operations through a single tool catalog.

The server speaks two transports:

⚠️ LOCAL USE ONLY. The server handles private keys. Do not expose it to the internet or use it with production wallets.

See CLAUDE.md for the full AI-facing tool reference and chain-specific concepts (chi, state-key format, address vs. public key, DEX workflow, error patterns).

Request Shape

flowchart LR
  Assistant["AI assistant or script"] --> Transport["MCP stdio or HTTP REST"]
  Transport --> Catalog["Shared tool catalog"]
  Catalog --> SDK["xian-tech-py"]
  SDK --> Node["Xian node RPC"]
  SDK --> Live["CometBFT live events"]
  SDK --> BDS["BDS indexed APIs"]
  Catalog --> Wallets["Local wallet operations"]
  Catalog --> Crypto["Local crypto helpers"]
  Catalog --> DEX["DEX helper tools"]

Related MCP server: gulltoppr

Quick Start

Build the Docker image (recommended):

git clone https://github.com/xian-technology/xian-mcp-server.git
cd xian-mcp-server
docker build --target pypi -t xian-mcp-server .

This standalone build installs published Python dependencies. To build against sibling SDK checkouts instead, use docker compose build or:

docker buildx build --target local --load -t xian-mcp-server \
  --build-context xian_py=../xian-py \
  --build-context xian_accounts=../xian-contracting/packages/xian-accounts \
  --build-context xian_runtime_types=../xian-contracting/packages/xian-runtime-types \
  .

Smoke-test the MCP handshake:

docker run --rm -i xian-mcp-server < test_requests.jsonl
# or, without Docker:
uv run xian-mcp-server < test_requests.jsonl
uv run python xian_server.py < test_requests.jsonl

You should see two JSON responses: an initialize response (id 1) and a tools/list response (id 2).

Use with Claude Desktop

Edit your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows, ~/.config/Claude/claude_desktop_config.json on Linux):

{
  "mcpServers": {
    "xian": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "xian-mcp-server"]
    }
  }
}

Quit Claude Desktop fully and restart it; the Xian tools will be available.

Use with LM Studio

In LM Studio's Program sidebar, choose Install → Edit mcp.json and add:

{
  "xian": {
    "command": "docker",
    "args": ["run", "-i", "--rm", "xian-mcp-server"]
  }
}

LM Studio reloads MCP servers automatically when the file is saved.

Run the HTTP Server

uv run xian-mcp-http                               # bare-metal
export XIAN_MCP_HTTP_TOKEN="$(openssl rand -hex 32)"
# Optional: publish Docker Compose HTTP on IPv6 loopback instead of IPv4.
# export HTTP_PUBLISH_HOST="::1"
docker compose up xian-mcp-http
docker run -p 127.0.0.1:8100:8100 \
  -e HTTP_HOST=0.0.0.0 \
  -e XIAN_MCP_HTTP_TOKEN="${XIAN_MCP_HTTP_TOKEN}" \
  xian-mcp-server xian-mcp-http

Endpoints:

curl http://localhost:8100/tools
curl -X POST http://localhost:8100/tools/get_balance \
     -H "Content-Type: application/json" \
     -d '{"address": "your_address_here"}'

HTTP binds to 127.0.0.1 by default in bare-metal mode. Docker examples bind the host port to 127.0.0.1 by default while the process listens on 0.0.0.0 inside the container. With Compose, set HTTP_PUBLISH_HOST=::1 to publish the host port on IPv6 loopback, then call http://[::1]:8100/tools.

Unsafe wallet/signing tools are hidden from GET /tools and rejected by POST /tools/{name} unless XIAN_MCP_ENABLE_UNSAFE_WALLET_TOOLS=1 is set. When unsafe tools are enabled, or when HTTP binds to a non-loopback address, set XIAN_MCP_HTTP_TOKEN and send it as a bearer token. IPv4 loopback, localhost, and IPv6 loopback binds such as ::1 or [::1] do not require a token unless unsafe tools are enabled or a token is explicitly configured. IPv6 wildcard :: and other non-loopback IPv6 binds require a token.

DEX discovery, quotes, and plans are read-only and remain available with the unsafe gate disabled. The three dex_submit_* tools are value-moving tools and use the same unsafe-wallet gate and HTTP bearer-token requirements as sends and legacy DEX helpers. Each planner stores an immutable canonical plan in a process-local registry and returns its complete audit JSON with an opaque plan_id, SHA-256 digest, issue time, and expiry. After confirmation, pass only that plan_id and the private key to the matching submitter. Submission claims the stored plan exactly once before wallet validation or network work, simulates calls by default, then submits its required approvals and exact router call. Plans expire after five minutes by default, may be evicted at the registry bound, and do not survive a server restart; create a fresh plan in those cases.

export XIAN_MCP_ENABLE_UNSAFE_WALLET_TOOLS=1
export XIAN_MCP_HTTP_TOKEN="$(openssl rand -hex 32)"

curl http://localhost:8100/tools \
     -H "Authorization: Bearer ${XIAN_MCP_HTTP_TOKEN}"
curl -X POST http://localhost:8100/tools/create_wallet \
     -H "Authorization: Bearer ${XIAN_MCP_HTTP_TOKEN}"

Browser CORS is disabled by default. To allow a local browser client, list exact origins with XIAN_MCP_HTTP_CORS_ORIGINS; wildcard CORS is rejected:

export XIAN_MCP_HTTP_CORS_ORIGINS="http://localhost:3000,http://127.0.0.1:3000"

The HTTP wrapper (http_server.py) is designed to be reusable with any MCP server that uses the TOOL_SPECS pattern; see the source for the create_app(tool_specs=...) helper.

Principles

• Local-only by default. The server is built around private-key custody. It must not be exposed to the internet or paired with production wallets.

• Two transports, one tool catalog. Stdio MCP and HTTP REST expose the exact same tools and schemas. The transport is a thin shell.

• AI-friendly safety conventions. Errors return human-readable strings. Private keys are never logged or echoed in responses. Confirmation is expected for any value-moving operation; see CLAUDE.md.

• xian-tech-py is the only SDK. All blockchain interactions go through xian-tech-py's sync / async clients. Live DEX waits use its CometBFT WebSocket watcher, while indexed reads wrap its BDS surface.

• Read-mostly indexed surface. BDS-backed reads (blocks, txs, events, state history, shielded sync) are read-only and most useful when pointed at a node with BDS-backed indexed APIs enabled.

Tool Surface

Use tools/list (see test_requests.jsonl) to discover the full schema.

create_hd_wallet(account_index=0) and create_hd_wallet_from_mnemonic(mnemonic, account_index=0) use the same indexed Xian mnemonic derivation as the browser/mobile wallets and Python's Wallet.from_mnemonic. The optional integer index ranges from 0 through 4294967295. Save the phrase and selected index to restore the same address. Results include numeric account_index, the normalized phrase, and Xian and Ethereum keys. The Ethereum helper keeps its default account 0, identified by numeric ethereum_account_index: 0 in the result. These tools remain behind the unsafe-wallet opt-in, and their results contain secret key material.

Configuration

The defaults target a local current-code stack. Drop overrides into a .env file (template in .env.example) when using docker-compose.

Key Files

• xian_server.py — stdio MCP server entrypoint.

• dex_plan_registry.py — bounded process-local storage for immutable, expiring, single-use DEX plans.

• http_server.py — reusable HTTP REST wrapper around the same tool specs.

• serialization.py — JSON-RPC and tool-result serialization helpers.

• mcp.json, custom_catalog.yaml — example client configurations.

• test_requests.jsonl — canonical MCP handshake smoke input.

• tests/ — unit/ (deterministic) and integration/ (live-network) coverage; shared fixtures in tests/shared.py.

• Dockerfile, docker-compose.yml — container build and runtime topology.

• CLAUDE.md — AI assistant integration guide and detailed tool reference.

Validation

The standard setup uses locked published dependencies and works without sibling checkouts. Mnemonic tools require xian-tech-py 0.5.2 or newer and use its Wallet.from_mnemonic API for canonical indexed Xian accounts.

uv sync --frozen --extra dev
uv run pytest -q                       # deterministic unit tests
docker run --rm -i xian-mcp-server < test_requests.jsonl   # MCP handshake smoke test

To test an unreleased sibling SDK explicitly after the standard setup:

uv pip install --no-sources \
  -e ../xian-contracting/packages/xian-runtime-types \
  -e ../xian-contracting/packages/xian-accounts \
  -e "../xian-py[eth,hd]"
uv run --no-sync pytest -q
uv run --no-sync xian-mcp-server < test_requests.jsonl

Use --no-sync while testing those overrides. Run uv sync --frozen --extra dev to return to the published dependency versions. Docker Compose and the local Docker target retain their explicit sibling build contexts.

Live-network integration tests are opt-in and submit small transactions against the configured dev node:

export XIAN_NODE_URL=http://127.0.0.1:27657
export XIAN_CHAIN_ID=xian-localnet-1
export XIAN_MCP_LIVE_PRIVATE_KEY=<funded-dev-private-key>
export XIAN_MCP_LIVE_TOKEN_SYMBOL=XDT
export XIAN_MCP_LIVE_TOKEN_CONTRACT=con_dex_demo_token
export XIAN_MCP_LIVE_DEX_TOKEN=con_dex_demo_token
export XIAN_MCP_LIVE_DEX_BASE=currency
# Optional: also add and remove a small liquidity position.
export XIAN_MCP_LIVE_DEX_LIQUIDITY=1

uv run pytest -q tests/integration/test_live_tool_surface.py

CI runs unit tests and the MCP handshake smoke test on every push and PR. Live integration tests run on a daily schedule and via manual workflow_dispatch.

Related Docs

• CLAUDE.md — AI-assistant integration guide, full tool reference, security guidelines, common workflows

• test_requests.jsonl — canonical MCP handshake smoke input

• xian-tech-py — the underlying Python SDK

Operational logs

Both entrypoints write bounded, single-line UTC diagnostics to stderr using timestamp | LEVEL | mcp/component | message | key=value records. Stdio stdout is reserved for MCP JSON-RPC. Failed tools carry a generated request ID, tool name, safe reason, exception type and stack locations; tool arguments, exception messages, locals, signing material and credential-bearing endpoints are omitted. Routine reads and fallback diagnostics are DEBUG; HTTP access logging is disabled.

The server creates no log files. Docker or the host supervisor owns retention of stderr: workspace Docker defaults are 50 MiB segments, five segments per container, with no age guarantee. Host capture expires files after seven days and caps its aggregate at 250 MiB, discarding older entries sooner when necessary.