Satoshkin AML/KYT MCP Server

MCP server for AML/KYT crypto wallet screening. It is designed to connect AI clients such as Claude Desktop, Claude Code, ChatGPT MCP clients, and internal agent tools to Satoshkin wallet risk checks.

This MCP server provides AI assistants with crypto compliance tools for AML (Anti-Money Laundering) and KYT (Know Your Transaction) screening. Compatible with Claude Desktop, Claude Code, and any MCP-compatible client.

With an API key configured, checks return real BitOK-backed data: risk score 0-100, risk level, source-of-funds tags, activity dates, and volume totals. Without a key the server runs in clearly-labeled mock mode.

Status

v0.2.0 performs real AML/KYT screening through the Satoshkin backend (POST /api-accounts/aml-check, BitOK data) when SATOSHKIN_API_KEY is set.

Without an API key the server runs in mock mode: deterministic, clearly-labeled placeholder responses that can never be mistaken for a real verdict.

This repository does not contain BitOK credentials, production AML/KYT business logic, user data, or paid-tier enforcement. Those belong in the private backend service.

Available Tool

check_wallet_aml

Checks a crypto wallet address for AML/KYT risk. Addresses are validated against per-chain formats client-side before any quota is spent.

Input:

{
  "address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
  "chain": "BTC"
}

Supported chain values:

• BTC
• ETH
• TRON
• USDT-ERC20
• USDT-TRC20

Real output (with SATOSHKIN_API_KEY):

{
  "address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
  "chain": "BTC",
  "checked_at": "2026-06-10T12:00:00.000Z",
  "risk_score": 17,
  "risk_level": "low",
  "tags": ["exchange"],
  "first_activity": "2021-01-01",
  "last_activity": "2026-06-01",
  "total_volume_in_usd": "1000.00",
  "total_volume_out_usd": "900.00",
  "source": "bitok",
  "cache_hit": false,
  "rate_limit": { "remaining": 999, "resets_at": "2026-06-10T13:00:00.000Z" },
  "balance": { "charged_usd": "0.55", "after_usd": "9.45" }
}

Errors come back as structured isError payloads with machine-readable codes: unauthorized, insufficient_balance, rate_limited, validation_error, bitok_upstream_error, bitok_timeout, upstream_unreachable, invalid_response, internal_error, and http_<status> (fallback when a backend error body has no error field). Every error payload also carries an http_status field.

Results are informational risk indicators, not legal or compliance advice.

Configuration

| Env var | Default | Purpose | |---|---|---| | SATOSHKIN_API_KEY | (unset = mock mode) | API key sk_live_* / sk_test_* issued by Satoshkin | | SATOSHKIN_API_BASE_URL | https://satoshkin.com | Backend base URL (staging override) | | SATOSHKIN_TIMEOUT_MS | 30000 | Request timeout; first-time checks may take several seconds |

Claude Desktop / Claude Code

This package is not published to npm yet. Use the public GitHub repository through npx.

Add this to your MCP settings:

{
  "mcpServers": {
    "satoshkin-aml": {
      "command": "npx",
      "args": ["-y", "github:satoshkin-dev/satoshkin-aml-mcp"],
      "env": {
        "SATOSHKIN_API_KEY": "sk_live_your_key_here"
      }
    }
  }
}

Omit the env block to run in mock mode.

For local development, use the built entrypoint:

{
  "mcpServers": {
    "satoshkin-aml": {
      "command": "node",
      "args": ["/absolute/path/to/satoshkin-aml-mcp/dist/index.js"]
    }
  }
}

Local Development

git clone https://github.com/satoshkin-dev/satoshkin-aml-mcp.git
cd satoshkin-aml-mcp
npm install
npm run build
npm test

Run the server locally:

npm run dev

Run the built server:

npm run build
node dist/index.js

Check Scope

Shipped in v0.2:

• Risk score 0-100 + risk level (low / medium / high)
• Source-of-funds tags
• First and last activity dates
• Total volume in and out (USD)
• Per-key rate limiting and billing through Satoshkin backend authentication

Planned next: counterparty and cluster analysis, allow/review/block decisions.

Monetization Model

The MCP server is a free open-source connector.

Real checks require a Satoshkin API key. Billing is per successful check ($0.55, debited from a prepaid key balance), the first real check per key is free, and cached repeat checks within 60 seconds are not charged. Keys are currently issued by Satoshkin support; a self-service dashboard is in development. Mock mode is free and unlimited.

Related Satoshkin Products

• P2P bot: https://satoshkin.com
• AML/KYT Telegram bot: https://t.me/SatoshkinKYTbot
• AML/KYT web app: planned

Use Cases

• OTC desks: Screen counterparty wallets before settling P2P trades
• Compliance officers: Quick wallet risk checks during AI-assisted workflows
• Crypto fund managers: Vet wallet addresses for sanctions/mixer exposure via AI agent
• Web3 builders: Add AML screening to Claude/ChatGPT-powered dApps
• Crypto journalists: Investigate wallet history with AI assistance

Why MCP Instead of REST API?

Traditional AML APIs (Chainalysis, Elliptic, TRM Labs) require:

• Custom integrations per AI client
• Backend infrastructure to broker calls
• Manual prompt engineering for context

This MCP server lets any AI assistant call AML checks natively, with structured input/output that the LLM understands. Install once, use across all your AI tools.

Roadmap

• [x] v0.1: Scaffold with mock checks
• [x] v0.2: Real BitOK integration via Satoshkin backend (per-check billing, free first check, mock mode without key)
• [ ] v0.3: Self-service key dashboard + top-up
• [ ] v0.4: Additional chains (Solana, BNB, Polygon)
• [ ] v0.5: Richer tag taxonomy and sanctions-specific flags
• [ ] v0.6: Cluster analysis and entity attribution

License

MIT