ST
Finance

Starknet MCP Server: StarknetID, Query Tools, Transfers

Use the MCP server to query Starknet data, resolve StarknetIDs, and perform secure, fast token transfers with reliable tools.

View on GitHub
Quick Install
npx -y @mcpdotdirect/starknet-mcp-server

Overview

The Starknet MCP Server implements a Model Context Protocol (MCP) backend focused on Starknet-specific utilities: resolving human-readable StarknetIDs, querying on-chain and indexer data, and executing secure token transfers. It bundles a small REST API and helper tools so applications and bots can reliably access Starknet information and perform transfers without re-implementing common plumbing (resolution, signing, provider selection, retries).

This server is useful when you want a single, hosted endpoint to:

  • translate user-friendly StarknetIDs into contract addresses,
  • run standardized Starknet queries (balances, token metadata, transaction status) across networks,
  • perform transfers with server-side signing, nonce management, and retry logic. It reduces integration complexity for wallets, services, or analytics dashboards that need dependable Starknet operations.

Features

  • Resolve StarknetID to an address and metadata
  • Standardized on-chain queries (balances, token info, tx status)
  • Secure server-side transfer execution with signature handling and retries
  • Support for multiple Starknet networks (configurable provider URLs)
  • Simple REST API with health and metrics endpoints
  • Pluggable storage/backing (environment-driven DB or in-memory for quick starts)
  • Rate limiting and authorization support for protected endpoints
  • Docker and Docker Compose deployment examples

Installation / Configuration

Prerequisites: Docker (recommended) or Node 18+ and PostgreSQL (optional).

Clone the repository:

git clone https://github.com/mcpdotdirect/starknet-mcp-server.git
cd starknet-mcp-server

Run with Docker:

# Build
docker build -t starknet-mcp-server .

# Run with environment variables
docker run -d \
  --name starknet-mcp \
  -p 8080:8080 \
  -e PORT=8080 \
  -e NETWORK=mainnet \
  -e PROVIDER_URL=https://starknet-mainnet.infura.io/v3/YOUR_KEY \
  -e DATABASE_URL=postgres://user:pass@db:5432/mcp \
  -e ADMIN_TOKEN="replace-me" \
  starknet-mcp-server:latest

Docker Compose (example):

version: '3.7'
services:
  mcp:
    image: starknet-mcp-server:latest
    ports: ["8080:8080"]
    environment:
      - PORT=8080
      - NETWORK=mainnet
      - PROVIDER_URL=https://starknet-mainnet.provider/YOUR_KEY
      - DATABASE_URL=postgres://user:pass@postgres:5432/mcp
      - ADMIN_TOKEN=replace-me
  postgres:
    image: postgres:14
    environment:
      POSTGRES_DB: mcp
      POSTGRES_USER: user
      POSTGRES_PASSWORD: pass
    volumes:
      - pgdata:/var/lib/postgresql/data
volumes:
  pgdata:

Local dev (Node):

npm install
cp .env.example .env
# edit .env with provider and DB info
npm run migrate
npm start

Important env vars:

  • PORT: HTTP server port (default 8080)
  • NETWORK: network label (e.g., mainnet, testnet)
  • PROVIDER_URL: Starknet RPC or indexer URL
  • DATABASE_URL: Postgres connection string (optional)
  • ADMIN_TOKEN: Bearer token for protected actions (transfers)

Available Tools / Resources

The server exposes a small REST API. Typical endpoints:

  • GET /health — basic liveness check
  • GET /metrics — Prometheus metrics (if enabled)
  • POST /mcp/resolve — resolve StarknetID to an address
    • body: { “starknetId”: “alice.stark” }
    • response: { “address”: “0x…”, “metadata”: { … } }
  • POST /mcp/query — generic Starknet queries
    • body: { “type”: “balance” | “tokenInfo” | “txStatus”, “params”: {…} }
  • POST /mcp/transfer — perform a signed token transfer (protected)
    • headers: Authorization: Bearer <ADMIN_TOKEN> or API Key
    • body: { “to”: “0x…”, “token”: “0x…”, “amount”: “1000000000000000000” }
    • response: { “txHash”: “0x…”, “status”: “submitted” }

SDK / example clients:

  • Minimal JavaScript fetch example:
const res = await fetch('https://your-mcp-host/mcp/resolve', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ starknetId: 'alice.stark' })
});
console.log(await res.json());

Use Cases

  1. Wallet backend: Use the MCP server to resolve a user’s StarknetID and show balances and token metadata. When the user initiates a transfer, have the server submit a pre-authorized transfer using a safe signing key and shared audit logs.

    • Steps: resolve -> query token balance -> create transfer -> monitor tx status via /mcp/query.

  2. Bot for payroll or airdrops: Build a job that reads a CSV of StarknetIDs, resolves them in bulk, batches transfers via /mcp/transfer, and checks confirmations from /mcp/query. The server manages nonces and retries to avoid duplicate or dropped transactions.

  3. Analytics dashboard: Centralize calls to the provider and indexer through the MCP server to normalize different network providers and cache commonly requested metadata (token info, name lookups). Use /metrics to monitor request rates and latencies.

  4. Automated reconciliation: Periodically query token balances and transaction receipts for a set of addresses. The MCP server can be configured to persist historical query results to the database for auditing and reconciliation pipelines.

Security and Operational Notes

  • Protect transfer endpoints with strong tokens and network-level controls. Keep private signing keys in secure vaults (do not commit them).
  • Configure rate limits and monitoring (Prometheus metrics) for production.
  • Use provider failover (multiple PROVIDER_URLs) if you need higher availability.
  • Run database backups and enable migrations when upgrading versions.

For full source, issues and contribution guidelines, see the GitHub repository: https://github.com/mcpdotdirect/starknet-mcp-server.

Tags:finance