Bit2me Mcp

Bit2Me MCP Server

[](https://github.com/bit2me-devs/bit2me-mcp/actions/workflows/ci.yml) [](https://github.com/bit2me-devs/bit2me-mcp/actions/workflows/deploy.yml) [](https://www.npmjs.com/package/@bit2me/mcp-server) [](https://opensource.org/licenses/MIT) [](https://scorecard.dev/viewer/?uri=github.com/bit2me-devs/bit2me-mcp) [](https://www.bestpractices.dev/projects/11511) [](https://www.typescriptlang.org/) [](https://nodejs.org/)

An MCP (Model Context Protocol) server to interact with the Bit2Me ecosystem. This server allows AI assistants like Claude to access real-time market data, manage wallets, execute trading operations, and query products like Earn and Loans.

For more information, visit: https://mcp.bit2me.com

Bit2Me is a leading cryptocurrency exchange based in Spain, offering a wide range of services including trading, staking (Earn), and loans. This MCP server acts as a bridge, enabling LLMs to perform actions and retrieve data securely from your Bit2Me account.

🚀 Features

• General: Asset information, account details, portfolio valuation, and self-introspection (general_describe_tool returns description, schema, and examples for any tool — useful for LLMs encountering a tool for the first time).
• Wallet Management: Query balances, transactions, and wallet (Pockets) details.
• Pro Trading: Manage orders (Limit, Market, Stop), query open orders, and transfer funds between Wallet and Pro.
• Earn & Loans: Manage Earn (Staking) strategies and collateralized loans.
• Operations: Execute trades, transfers, and withdrawals securely.
• Idempotency & Retries: Every write tool auto-generates an idempotency key; failed POST/DELETE calls retry with exponential backoff + jitter, making operations safe to retry without duplicates.
• Decimal Precision: Portfolio valuation uses decimal.js — no floating-point drift on large balances or high-precision assets.
• Expanded PII Redaction: Logs automatically scrub email addresses, IBANs, phone numbers, KYC fields, JWT-shaped tokens, and long base64 blobs, in addition to API keys and signatures.
• Monotonic Nonces: API-key signing uses a strictly-increasing nonce counter, preventing replay attacks even under high concurrency.
• Audit Log: Every write tool (order creation, withdrawals, earn deposits, loan operations, …) appends a tamper-evident JSON line on both success and failure. Set AUDIT_LOG_PATH to write to a dedicated file; otherwise audit lines are emitted via the logger with audit: true.
• Parametrized Prompts: analyze_portfolio and market_summary accept arguments. Three new prompts ship out of the box: tax_report, dca_plan, and loan_health_check.

🛠️ Available Tools & API Endpoints

The server currently exposes 48 tools grouped as follows:

• 4 General tools (including general_describe_tool for self-introspection)
• 8 Broker (Simple Trading) tools
• 4 Wallet tools
• 14 Pro Trading tools
• 11 Earn (Staking) tools
• 7 Loan tools

Full descriptions, response schemas, Bit2Me REST endpoints and usage notes live in [TOOLS_DOCUMENTATION.md](./TOOLS_DOCUMENTATION.md).

📋 Documentation & Schemas

All tool responses are normalised for LLM consumption (consistent naming, flattened payloads, concise metadata). Use the following references when developing new tooling:

• [TOOLS_DOCUMENTATION.md](./TOOLS_DOCUMENTATION.md) – Auto-generated catalogue with descriptions, Bit2Me endpoints and response schemas for each tool.
• [data/tools.json](./data/tools.json) – Source metadata powering the landing page (includes request/response schemas and examples for each tool).

⚙️ Installation and Configuration

Prerequisites

• Node.js: v20 or higher.
• Bit2Me Account: You need a verified Bit2Me account.

🔑 Authentication Methods

API Keys (Recommended)

The recommended way to authenticate is using API Keys. This method is secure, granular, and designed for programmatic access.

1. Go to your Bit2Me API Dashboard.
2. Click on "New Key".
3. Select the permissions you need (e.g., Wallets, Trading, Earn, Loans).

> ⚠️ Security Note: This MCP server does NOT support crypto withdrawals to external blockchain addresses or transfers to other users. For security best practices, please DO NOT enable "Withdrawal" permissions on your API Key. Internal transfers between your own Bit2Me wallets (Wallet ↔ Pro ↔ Earn) are fully supported.

JWT Session Token (Alternative)

All tools support an optional jwt parameter for session-based authentication. This is useful for:

• Multi-tenant applications: Where each request is made on behalf of a different user.
• Web integrations: Where users are already authenticated via the Bit2Me web interface.

When the jwt parameter is provided, the server will use cookie-based authentication instead of API Keys.

// Example: Using JWT session token
const result = await mcpClient.callTool("wallet_get_pockets", {
    symbol: "BTC",
    jwt: "user_session_token_here", // Optional - uses API keys if omitted
});

> 📝 Note: API Keys are recommended for most use cases. The jwt parameter should only be used when building multi-tenant applications or web integrations where users have existing Bit2Me sessions.

Steps

1. Clone the repository:

``bash git clone https://github.com/bit2me-devs/bit2me-mcp.git cd bit2me-mcp ``

1. Install dependencies:

``bash npm install ``

1. Configure environment variables:

Create a .env file in the root directory:

``bash cp .env.example .env ``

Edit .env and add your keys:

```env BIT2MEAPIKEY=YOURBIT2MEACCOUNTAPIKEY BIT2MEAPISECRET=YOURBIT2MEACCOUNTAPISECRET

# Optional Configuration BIT2MEGATEWAYURL=https://gateway.bit2me.com # Must be HTTPS (localhost/127.x are exempt) BIT2MEREQUESTTIMEOUT=30000 # Request timeout in ms (default: 30000) BIT2MEMAXRETRIES=3 # Max retries for rate limits (default: 3) BIT2MERETRYBASEDELAY=1000 # Base delay for backoff in ms (default: 1000) BIT2MELOGLEVEL=info # Log level: debug, info, warn, error (default: info) LOGFORMAT=json # Optional: "json" for log aggregators; default is human-readable # AUDITLOGPATH=/var/log/bit2me-mcp/audit.log # Append-only write-tool audit log ```

> 💡 QA/Staging: Use BIT2ME_GATEWAY_URL to point to different environments (e.g., https://qa-gateway.bit2me.com for QA testing).

> 🔒 File permissions: The .env file holds API credentials. Restrict it to the owner only: > > ``bash > chmod 600 .env > ` > > A pre-commit hook (.husky/check-env-perms.sh) prints a warning when the local .env mode is more permissive than 600`.

1. Build the project:

``bash npm run build ``

🖥️ Usage with Claude Desktop

To use this server with the Claude Desktop application, add the following configuration to your claude_desktop_config.json file:

MacOS

~/Library/Application Support/Claude/claude_desktop_config.json

Windows

%APPDATA%\Claude\claude_desktop_config.json

{
    "mcpServers": {
        "bit2me": {
            "command": "node",
            "args": ["/absolute/path/to/bit2me-mcp/build/index.js"],
            "env": {
                "BIT2ME_API_KEY": "YOUR_BIT2ME_ACCOUNT_API_KEY",
                "BIT2ME_API_SECRET": "YOUR_BIT2ME_ACCOUNT_API_SECRET"
            }
        }
    }
}

> Note: Replace /absolute/path/to/... with the actual full path to your project.

Using a Custom Gateway (QA/Staging)

For testing against different environments, add the BIT2ME_GATEWAY_URL variable:

{
    "mcpServers": {
        "bit2me": {
            "command": "node",
            "args": ["/absolute/path/to/bit2me-mcp/build/index.js"],
            "env": {
                "BIT2ME_API_KEY": "YOUR_BIT2ME_ACCOUNT_API_KEY",
                "BIT2ME_API_SECRET": "YOUR_BIT2ME_ACCOUNT_API_SECRET",
                "BIT2ME_GATEWAY_URL": "https://qa-gateway.bit2me.com"
            }
        }
    }
}

🛡️ Security

Security Policy

For detailed information about reporting vulnerabilities and our security policy, please see [SECURITY.md](./SECURITY.md).

Best Practices

• API Keys: Never commit API keys to version control. The pre-commit hook runs gitleaks (if installed) to block accidental secret commits.
• Permissions: Use minimal permissions. Avoid "Withdrawal" permissions for MCP usage.
• HTTPS Gateway: BIT2ME_GATEWAY_URL is validated at startup — only https:// URLs are accepted. Plain http:// is rejected except for localhost / 127.x addresses (local development only).
• Monotonic Nonces: API-key signing uses a strictly-increasing nonce counter so concurrent requests cannot generate replay-vulnerable signatures.
• Expanded PII Redaction: The logger scrubs API keys, signatures, JWTs, emails, IBANs, phone numbers, KYC fields, and long base64 blobs before writing any line to stderr.
• Audit Log: Every write tool appends an append-only JSON entry (tool name, sanitised args, outcome, correlation ID, SHA-256 fingerprint of the session token — never the token itself). Set AUDIT_LOG_PATH to persist to a file.

⚠️ Rate Limits & Error Handling

The Bit2Me API enforces rate limits to ensure stability.

• 429 Too Many Requests: If the server hits a rate limit, it will automatically retry the request after a 1-second delay (up to 3 retries).
• Console Warnings: You may see warnings in the logs if rate limits are hit.
• Best Practice: Avoid asking for massive amounts of data in a very short loop.
• Exponential Backoff: The server now uses exponential backoff with jitter for retries to handle rate limits more gracefully.

📊 Logging

The server implements a structured logging system that automatically sanitizes sensitive data (API keys, signatures, JWTs, emails, IBANs, and other PII). You can control the verbosity using the BIT2ME_LOG_LEVEL environment variable:

• debug: Detailed request/response logs (useful for development)
• info: Startup and operational events (default)
• warn: Rate limits and non-critical issues
• error: API errors and failures

Set LOG_FORMAT=json to switch the logger to a single-JSON-object-per-line format suitable for log aggregators (Loki, Datadog, CloudWatch, etc.). The default is human-readable.

All logs are written to stderr; stdout is reserved for the MCP JSON-RPC frame.

🧵 Concurrency Model

Each incoming tool call runs inside its own AsyncLocalStorage boundary. The store carries:

• correlationId: a UUID generated per request, included in every log line
• sessionToken (jwt): the optional per-call session token, never logged in the clear
• toolName, startTime: useful for metrics / audit

Two requests that arrive concurrently — for example two different users hitting the HTTP transport with their own JWTs — never share state. The legacy global-context fallbacks remain for unit tests that run outside a runWithContext boundary, but production code paths always create a context. See tests/concurrency.test.ts and tests/http-transport.test.ts for the regression coverage.

Per-request state stored via memoizePerRequest() (e.g. wallet pockets fetched multiple times during a single broker quote) is keyed by correlationId and cleared in the finally block of executeTool() so the cache cannot grow unbounded.

🚢 Operating in Production

Two binaries ship with this package:

• bit2me-mcp-server — the original stdio transport, designed to be spawned by a single LLM client (Claude Desktop, Cursor, …).
• bit2me-mcp-http — the multi-tenant HTTP/SSE transport (src/index-http.ts). Each request supplies its own credentials in headers (X-Bit2Me-Api-Key + X-Bit2Me-Api-Secret or Authorization: Bearer ). TLS termination is delegated to a reverse proxy.

Recommended environment variables for the HTTP binary:

• MCP_HTTP_HOST / MCP_HTTP_PORT (default 127.0.0.1:3000)
• MCP_HTTP_AUTH_MODE: api_key (default), jwt, or both
• LOG_FORMAT=json for structured logs
• AUDIT_LOG_PATH=/var/log/bit2me-mcp/audit.log to ship audit lines to a file

Choosing an auth mode (HTTP transport)

The HTTP transport accepts API-key credentials and Bit2Me session JWTs. Both modes are first-class — the right choice depends on where the server is bound and who is calling it, not on a one-size-fits-all rule. The full threat model and rationale live in [docs/adr/0001-valet-key-http-credentials.md](./docs/adr/0001-valet-key-http-credentials.md).

| Topology | Recommended MCP_HTTP_AUTH_MODE | Why | | ---------------------------------------------------------------------- | ---------------------------------------------------------- | -------------------------------------------------------------------------------------- | | stdio (Cursor, Claude Desktop, local CLI) | n/a — use BIT2ME_API_KEY / BIT2ME_API_SECRET in .env | Single-process, no network hop; scopes are enforced by the Bit2Me dashboard. | | HTTP bound to loopback (127.0.0.1, ::1, localhost) | api_key | Credentials never leave the host. | | HTTP on a private network / VPN behind a TLS-terminating reverse proxy | api_key | Encrypted hop; scopes enforced by the Bit2Me dashboard; operator owns the proxy chain. | | HTTP exposed on the public internet for a single operator | jwt | Bit2Me JWTs auto-expire (~15 min); the leak window is shorter. | | HTTP shared by multiple third-party integrators | jwt | Independent revocation per integrator without rotating the master credentials. |

Hard rules that apply regardless of the mode you pick:

• Mint API keys with the smallest scope that satisfies the caller's use

case. Read-only when possible. Never enable Withdrawal scopes for MCP usage — the MCP server intentionally does not support external withdrawals, so granting that permission only widens the blast radius of a leak.

• Always put the HTTP transport behind TLS on any non-loopback bind.

Plain HTTP on 0.0.0.0 is a misconfiguration regardless of the auth mode.

• The server emits a startup WARN log if api_key/both is active on a

non-loopback host so operators are nudged toward a TLS-terminating proxy or the JWT mode.

• Credential headers (X-Bit2Me-Api-Key, X-Bit2Me-Api-Secret,

Authorization) are scrubbed from every structured log line before it reaches stderr.

Built-in observability endpoints (HTTP transport only):

• GET /health — liveness + Bit2Me reachability + cache/circuit-breaker/rate-limiter snapshot. Cached for 30s.
• GET /metrics — Prometheus text-format counters (bit2me_mcp_tool_calls_total, bit2me_mcp_tool_errors_total, bit2me_mcp_tool_duration_avg_ms).

Reliability features active by default:

• Circuit breaker on the upstream Bit2Me API (src/utils/circuit-breaker.ts).
• Per-endpoint rate limiter with exponential backoff + jitter.
• Idempotency keys on every write tool (pro_create_order, loan_create, `earn_de

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: bit2me-devs
• Source: bit2me-devs/bit2me-mcp
• License: MIT
• Homepage: http://mcp.bit2me.com/

Install and usage instructions live in the source repository linked above.