bitso-mcp

blaze-xyz/bitso-mcp

3.2

If you are the rightful owner of bitso-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

An MCP server for the Bitso API that provides tools to access withdrawals and fundings data, built with TypeScript.

Tools
6
Resources
0
Prompts
0

Bitso MCP Server

An MCP server for the Bitso API that provides tools to access withdrawals and fundings data. Built with TypeScript, featuring comprehensive testing, dual transport support, and production-ready best practices.

Features

๐Ÿฆ Bitso API Integration

  • Complete Withdrawals API support (list, get by ID, get by multiple IDs, get by origin IDs)
  • Complete Fundings API support (list, get by ID)
  • Proper authentication with API key/secret and HMAC signature
  • Support for all API filtering and pagination parameters

๐Ÿš€ Production Ready

  • Dual transport support (stdio for Claude Desktop, HTTP for development)
  • Comprehensive error handling and logging
  • Type-safe configuration with Zod validation
  • Project-root-aware file logging system

๐Ÿงช Comprehensive Testing

  • Two-tier testing strategy (unit + integration tests)
  • Real MCP protocol testing (not mocked functions)
  • MSW for consistent API mocking
  • High test coverage with Vitest

๐Ÿ› ๏ธ Developer Experience

  • Hot reloading with TypeScript watch mode
  • Tool generation script
  • ESM support with proper module resolution
  • CI/CD pipeline with GitHub Actions

๐Ÿ“ฆ Best Practices

  • Modular tool organization
  • Zod schema validation for all inputs
  • Structured logging with file output
  • Caching with configurable TTL

Quick Start

1. Setup

npm install

2. Configure Environment

cp .env.example .env
# Edit .env with your Bitso API credentials

Required environment variables:

  • BITSO_API_KEY: Your Bitso API key
  • BITSO_API_SECRET: Your Bitso API secret

3. Build and Test

# Build the project
npm run build

# Run tests
npm run test

# Start development server (HTTP mode)
npm run start:http

4. Add to Claude Desktop

Add to your Claude Desktop configuration (claude_desktop_config.json):

{
  "mcpServers": {
    "bitso-mcp-server": {
      "command": "node",
      "args": ["/path/to/bitso-mcp-server/dist/src/index.js"],
      "env": {
        "BITSO_API_KEY": "your-bitso-api-key",
        "BITSO_API_SECRET": "your-bitso-api-secret"
      }
    }
  }
}

Available Tools

The server provides 6 tools to interact with the Bitso API:

Withdrawals Tools

  1. list_withdrawals - List withdrawals with optional filtering

    • Parameters: currency, limit, marker, method, origin_id, status, wid
  2. get_withdrawal - Get specific withdrawal by ID

    • Parameters: wid (required)
  3. get_withdrawals_by_ids - Get multiple withdrawals by comma-separated IDs

    • Parameters: wids (required, e.g., "wid1,wid2,wid3")
  4. get_withdrawals_by_origin_ids - Get withdrawals by client-supplied origin IDs

    • Parameters: origin_ids (required, e.g., "origin1,origin2,origin3")

Fundings Tools

  1. list_fundings - List fundings with optional filtering

    • Parameters: limit, marker, method, status, fids
  2. get_funding - Get specific funding by ID

    • Parameters: fid (required)

Development Guide

Project Structure

src/
โ”œโ”€โ”€ tools/           # MCP tool implementations
โ”‚   โ””โ”€โ”€ bitso-tools.ts  # Bitso API tools
โ”œโ”€โ”€ utils/           # Shared utilities
โ”‚   โ””โ”€โ”€ logging.ts   # Project-root-aware logging
โ”œโ”€โ”€ client.ts        # Bitso API client with authentication
โ”œโ”€โ”€ config.ts        # Environment configuration
โ”œโ”€โ”€ types.ts         # TypeScript type definitions
โ””โ”€โ”€ index.ts         # Main server entry point

tests/
โ”œโ”€โ”€ unit/            # Fast unit tests with MSW mocking
โ”œโ”€โ”€ integration/     # Real MCP protocol tests
โ”œโ”€โ”€ helpers/         # Test utilities
โ”‚   โ”œโ”€โ”€ mcp-test-helper.ts
โ”‚   โ”œโ”€โ”€ test-server-factory.ts
โ”‚   โ””โ”€โ”€ test-config.ts
โ”œโ”€โ”€ mocks/           # MSW request handlers
โ””โ”€โ”€ setup.ts         # Test environment setup

Creating New Tools

Use the built-in tool generator:

npm run build
npm run create-tool

Or create manually following the pattern in src/tools/bitso-tools.ts:

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { z } from "zod";

const MyToolSchema = z.object({
  param: z.string().min(1, "Parameter is required"),
});

export function registerMyTools(server: McpServer, client: BitsoApiClient): void {
  server.tool(
    "my_tool",
    {
      description: "Description of what the tool does",
      inputSchema: {
        type: "object",
        properties: {
          param: {
            type: "string",
            description: "Parameter description",
          },
        },
        required: ["param"],
      },
    },
    async (params): Promise<ToolResult> => {
      try {
        const validatedParams = MyToolSchema.parse(params);
        
        // Your tool logic here
        
        return {
          content: [
            {
              type: "text",
              text: "Tool response"
            }
          ]
        };
      } catch (error) {
        // Error handling
        return {
          content: [
            {
              type: "text",
              text: `Error: ${error instanceof Error ? error.message : String(error)}`
            }
          ]
        };
      }
    }
  );
}

Testing Strategy

This template uses a two-tier testing approach:

Unit Tests (tests/unit/)
  • Test business logic in isolation
  • Mock external APIs using MSW
  • Fast execution, run frequently during development
  • Focus on data transformations, caching, validation
Integration Tests (tests/integration/)
  • Test through real MCP protocol
  • Use actual MCP server instances
  • Validate tool registration and MCP compliance
  • Ensure proper request/response formatting
# Run unit tests (fast)
npm run test:unit

# Run integration tests (slower, full MCP protocol)
npm run test:integration

# Run all tests with coverage
npm run test:coverage

Transport Modes

Stdio Transport (Production)

Used by Claude Desktop and other MCP clients:

npm start
# or
node dist/src/index.js
HTTP Transport (Development)

Useful for debugging and development:

npm run start:http
# Server available at http://localhost:3000/mcp

Logging and Debugging

The template includes a sophisticated logging system:

  • Debug logs: Written to mcp-debug.log in project root
  • Project-root-aware: Works from both source and compiled code
  • Structured logging: JSON formatting for complex data
  • Console output: Errors also logged to stderr

Check logs during development:

tail -f mcp-debug.log

Configuration Management

Configuration uses Zod for type-safe validation:

// src/config.ts
const ConfigSchema = z.object({
  apiKey: z.string().min(1, 'API_KEY environment variable is required'),
  apiEndpoint: z.string().url().default('https://api.example.com'),
  // ... other config
});

Environment variables are validated on startup with clear error messages.

API Integration

Client Pattern

The template includes a robust API client pattern:

// Automatic caching
const resources = await client.getResources(); // Cached for 5 minutes

// Error handling
try {
  const resource = await client.getResource(id);
} catch (error) {
  // Errors are logged and can be handled
}

// Connection testing
const isHealthy = await client.testConnection();

Bitso API Authentication

The server uses HMAC-SHA256 authentication required by the Bitso API:

// Authentication headers are automatically generated
const authHeaders = {
  'key': config.apiKey,
  'signature': hmacSignature,  // Generated using API secret
  'nonce': timestamp
};

Each request is signed using:

  • API Secret (from environment)
  • HTTP method
  • Request path
  • Request body (if any)
  • Current timestamp as nonce

Deployment

Building for Production

npm run build
npm test

CI/CD

The template includes a GitHub Actions workflow (.github/workflows/ci.yml):

  • Unit tests: Fast feedback on basic functionality
  • Integration tests: Full MCP protocol validation
  • Coverage reporting: Ensure code quality
  • Build validation: Verify compilation

Environment Variables

Production deployment requires:

BITSO_API_KEY=your-production-api-key
BITSO_API_SECRET=your-production-api-secret
BITSO_API_ENDPOINT=https://api.bitso.com  # Production endpoint
CACHE_TTL_SECONDS=300
TIMEOUT=30000

Best Practices

Tool Development

  1. Always use Zod schemas for parameter validation
  2. Return MCP-compliant responses with { content: [...] } format
  3. Handle errors gracefully with user-friendly messages
  4. Log extensively for debugging and monitoring
  5. Test through MCP protocol using integration tests

Error Handling

// Good: MCP-compliant error response
return {
  content: [
    {
      type: "text",
      text: `Error: ${error.message}`
    }
  ]
};

// Bad: Throwing unhandled errors
throw new Error("Something went wrong");

Performance

  • Use caching for expensive API calls
  • Implement request timeouts
  • Log performance metrics
  • Monitor API rate limits

Troubleshooting

Common Issues

Tool not appearing in Claude:

  1. Check build succeeded: npm run build
  2. Restart Claude Desktop
  3. Check mcp-debug.log for errors
  4. Verify claude_desktop_config.json configuration

Tests failing:

  1. Run unit tests first: npm run test:unit
  2. Check MSW handlers match your API expectations
  3. Verify integration tests use real MCP server instances

API connection issues:

  1. Verify environment variables are set
  2. Test API credentials manually
  3. Check network connectivity and firewalls
  4. Review API endpoint URLs

Debug Mode

Enable detailed logging:

DEBUG=true npm start

Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Add tests for new functionality
  4. Ensure all tests pass: npm test
  5. Build successfully: npm run build
  6. Submit a pull request

License

MIT License. See for details.

Related Resources