Ryno-Crypto-Mining-Services/braiins-pool-mcp-server

Braiins Pool MCP Server

A Model Context Protocol (MCP) server providing seamless integration with the Braiins Pool API for Bitcoin mining operations. This server enables AI assistants like Claude, GitHub Copilot, and Cursor to interact with mining pool data, monitor performance, and manage configurations through natural language.

Table of Contents

• Overview
• Features
• Prerequisites
• Installation
• Configuration
• Usage
• Available Tools
• Architecture
• Development
• Testing
• Contributing
• Troubleshooting
• Documentation
• License

Overview

The Braiins Pool MCP Server bridges AI-powered development environments with Braiins Pool, one of the world's oldest Bitcoin mining pools. By implementing the Model Context Protocol, this server transforms complex API interactions into conversational commands that AI agents can understand and execute.

What is MCP?

Model Context Protocol (MCP) is an open standard that enables AI applications to securely connect with external data sources and tools. It provides:

• Standardized Communication: Unified interface for AI-tool integration
• Secure Connections: Built-in authentication and authorization
• Extensible Architecture: Easy addition of new capabilities
• Multi-Client Support: Works with Claude Desktop, Cursor, VS Code Copilot, and more

Why This MCP Server?

Traditional mining pool APIs require:

• Manual HTTP request construction
• Authentication header management
• Response parsing and error handling
• Deep knowledge of endpoint structures

With this MCP server, you simply ask:

"Show me my worker hashrates for the last 24 hours"

"What's the total BTC earned this month?"

"List all offline workers and their last seen time"

Features

Core Capabilities

• Worker Monitoring: Real-time hashrate, temperature, and status tracking
• Earnings Analytics: Historical and projected revenue calculations
• Pool Statistics: Network difficulty, block discovery, and pool performance
• User Management: Multi-account support with credential isolation
• Configuration Control: Dynamic pool settings and payout configuration

Technical Highlights

• ✅ Full TypeScript Implementation: Type-safe API interactions
• ✅ OAuth 2.0 Support: Secure token-based authentication
• ✅ Rate Limiting Protection: Built-in request throttling
• ✅ Error Recovery: Automatic retry with exponential backoff
• ✅ Streaming Responses: Efficient data transfer for large datasets
• ✅ Caching Layer: Redis-compatible caching for frequently accessed data

Prerequisites

Required

• Node.js: v18.0.0 or higher (download)
• npm: v9.0.0 or higher (included with Node.js)
• Braiins Pool Account: Active account with API access (sign up)

Optional

• MCP Client: Claude Desktop, Cursor, or VS Code with Copilot
• Docker: For containerized deployment
• Redis: For production caching (optional)

System Requirements

Installation

Quick Start (NPM)

# Install globally
npm install -g @ryno-crypto/braiins-pool-mcp-server

# Or install locally in project
npm install @ryno-crypto/braiins-pool-mcp-server

From Source

# Clone repository
git clone https://github.com/Ryno-Crypto-Mining-Services/braiins-pool-mcp-server.git
cd braiins-pool-mcp-server

# Install dependencies
npm install

# Build TypeScript
npm run build

# Run tests
npm test

Docker Deployment

Build Locally

# Build the Docker image
docker build -t braiins-pool-mcp-server .

# Run the container (MCP uses stdio, not HTTP ports)
docker run --rm -i \
  -e BRAIINS_API_KEY=your_api_key \
  braiins-pool-mcp-server

Using Docker Compose

Two Docker Compose configurations are available:

Basic Setup (No Redis)

# Set your API key
export BRAIINS_API_KEY=your_api_key

# Start the MCP server
docker compose up -d

# View logs
docker compose logs -f

With Redis Caching

# Set your API key
export BRAIINS_API_KEY=your_api_key

# Start MCP server with Redis and Redis Commander
docker compose -f docker-compose.redis.yml up -d

# Access Redis Commander UI
open http://localhost:8081

# View logs
docker compose -f docker-compose.redis.yml logs -f

Pull from Docker Hub

# Pull pre-built image
docker pull rynocrypto/braiins-pool-mcp-server:latest

# Run container
docker run --rm -i \
  -e BRAIINS_API_KEY=your_api_key \
  rynocrypto/braiins-pool-mcp-server:latest

Configuration

Environment Variables

Create a .env file in your project root:

# Required
BRAIINS_API_KEY=your_api_key_here

# Optional
BRAIINS_API_BASE_URL=https://pool.braiins.com/api/v1
REDIS_URL=redis://localhost:6379
REDIS_ENABLED=true
LOG_LEVEL=info
LOG_FORMAT=pretty

MCP Client Configuration

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "braiins-pool": {
      "command": "node",
      "args": ["/path/to/braiins-pool-mcp-server/dist/index.js"],
      "env": {
        "BRAIINS_API_KEY": "your_api_key"
      }
    }
  }
}

Cursor / VS Code

Add to .cursorrules or .vscode/mcp.json:

{
  "mcp": {
    "servers": {
      "braiins-pool": {
        "command": "npx",
        "args": ["@ryno-crypto/braiins-pool-mcp-server"],
        "env": {
          "BRAIINS_API_KEY": "${env:BRAIINS_API_KEY}"
        }
      }
    }
  }
}

API Key Generation

1. Log in to Braiins Pool
2. Navigate to Settings → Access Tokens
3. Click Generate New Token
4. Copy the API token immediately (shown only once)
5. Set as BRAIINS_API_KEY environment variable

Usage

Basic Examples

Check Worker Status

// In Claude Desktop or Cursor
"Show me the status of all my workers"

// MCP Server executes:
GET /workers
Response: {
  "workers": [
    {
      "name": "miner-01",
      "hashrate": "100 TH/s",
      "status": "active",
      "last_share": "2024-12-15T13:15:00Z"
    }
  ]
}

Analyze Earnings

"Calculate my BTC earnings for December 2024"

// Server aggregates:
// 1. Fetch daily payouts
// 2. Sum amounts
// 3. Apply exchange rate
// Returns formatted report

Advanced Workflows

Performance Monitoring

// Multi-step analysis
"Compare this week's hashrate to last week and explain any drops"

// Server orchestrates:
// 1. get_hashrate_history(start: -14d, end: -7d)
// 2. get_hashrate_history(start: -7d, end: now)
// 3. compute_difference()
// 4. check_downtime_events()
// 5. generate_summary()

Automated Alerting

// Set up monitoring (coming soon)
"Alert me if any worker goes offline for more than 10 minutes"

// Creates webhook subscription
// Polls /workers/status every 5 min
// Sends notification on condition match

Available Tools

Worker Management

Earnings & Payouts

Pool Statistics

Configuration

Architecture

System Design

┌─────────────────┐
│  MCP Client     │  (Claude, Cursor, VS Code)
│  (AI Assistant) │
└────────┬────────┘
         │ MCP Protocol (JSON-RPC 2.0)
         │
┌────────▼────────┐
│  MCP Server     │
│  - Tool Router  │  ← Validates requests
│  - Auth Manager │  ← Handles API keys
│  - Cache Layer  │  ← Redis/in-memory
└────────┬────────┘
         │ HTTPS + OAuth 2.0
         │
┌────────▼────────┐
│ Braiins Pool    │
│ REST API        │
└─────────────────┘

Component Breakdown

Server Core (src/server/)

• index.ts: MCP protocol implementation
• tools.ts: Tool definitions and handlers
• auth.ts: API authentication logic

API Client (src/api/)

• client.ts: HTTP request wrapper
• endpoints.ts: Braiins API endpoint mappings
• types.ts: TypeScript interfaces

Utilities (src/utils/)

• cache.ts: Response caching
• ratelimit.ts: Request throttling
• logger.ts: Structured logging

For detailed architecture documentation, see .

Development

Setup Development Environment

# Fork and clone
git clone https://github.com/YOUR_USERNAME/braiins-pool-mcp-server.git
cd braiins-pool-mcp-server

# Install dependencies
npm install

# Copy environment template
cp .env.example .env

# Start development server with hot reload
npm run dev

Project Scripts

npm run build      # Compile TypeScript → JavaScript
npm run dev        # Watch mode with auto-reload
npm test           # Run test suite
npm run test:watch # Continuous testing
npm run lint       # ESLint checks
npm run format     # Prettier formatting
npm run typecheck  # TypeScript validation

Code Style

This project uses:

• ESLint: Airbnb base config with TypeScript
• Prettier: 2-space indentation, single quotes
• Husky: Pre-commit hooks for linting
• Commitlint: Conventional commits enforced

Example commit:

git commit -m "feat(api): add worker restart endpoint"
git commit -m "fix(cache): resolve Redis connection timeout"
git commit -m "docs(readme): update installation instructions"

Testing

Unit Tests

# Run all tests
npm test

# Run specific test file
npm test -- worker.test.ts

# With coverage report
npm test -- --coverage

Integration Tests

# Requires valid API credentials
BRAIINS_API_KEY=test_key npm run test:integration

Manual Testing with MCP Inspector

# Install MCP Inspector
npm install -g @modelcontextprotocol/inspector

# Start server in inspector
mcp-inspector npx @ryno-crypto/braiins-pool-mcp-server

# Opens UI at http://localhost:6274

Contributing

We welcome contributions! Please see for guidelines.

Quick Contribution Workflow

1. Fork the repository
2. Create feature branch: git checkout -b feature/amazing-feature
3. Commit changes: git commit -m 'feat: add amazing feature'
4. Push to branch: git push origin feature/amazing-feature
5. Open Pull Request with description

Development Resources

• MCP Specification
• Braiins Pool API Docs
• TypeScript MCP SDK

Troubleshooting

Common Issues

"Authentication Failed"

Problem: Invalid API key or secret

Solution:

# Verify credentials
echo $BRAIINS_API_KEY

# Regenerate key at pool.braiins.com/settings/api
# Update .env file

"Rate Limit Exceeded"

Problem: Too many API requests

Solution:

# Increase window in .env
RATE_LIMIT_WINDOW_MS=120000  # 2 minutes

# Or reduce request frequency in client

"Connection Timeout"

Problem: Network or API issues

Solution:

// Check API status
curl https://pool.braiins.com/health

// Enable debug logging
LOG_LEVEL=debug npm start

"Tool Not Found"

Problem: MCP client can't discover tools

Solution:

# Restart MCP server
pkill -f braiins-pool-mcp-server
npm start

# Clear Claude Desktop cache (macOS)
rm -rf ~/Library/Application\ Support/Claude/cache

Getting Help

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Email: support@rynocrypto.com
• Discord: Braiins Community (mention @ryno-mcp)

Documentation

Additional Resources

• : Complete endpoint documentation
• : System design deep dive
• : Multi-agent setup patterns
• : Roadmap and milestones
• : Advanced workflows

Integration Guides

• : Step-by-step Claude configuration
• : VS Code integration
• : Cursor IDE setup

Roadmap

Current Version: 1.0.0

• Core MCP protocol implementation
• Worker monitoring tools
• Earnings tracking
• Basic caching

Version 1.1.0 (Q1 2025)

• WebSocket support for real-time updates
• Multi-pool aggregation (Braiins + Foundry + F2Pool)
• Historical analytics (30/60/90 day reports)
• Export to CSV/JSON

Version 2.0.0 (Q2 2025)

• Braiins OS API integration (miner firmware control)
• Automated alerting via webhooks
• AI-powered anomaly detection
• Mobile app companion

Security

Reporting Vulnerabilities

Do not open public GitHub issues for security bugs. Instead:

1. Email: security@rynocrypto.com
2. Include: reproduction steps, impact assessment, suggested fix
3. Response: We aim to respond within 48 hours

Security Best Practices

• Never commit API keys to version control
• Use environment variables for secrets
• Rotate keys every 90 days
• Enable 2FA on Braiins Pool account
• Audit access logs regularly

License

This project is licensed under the Apache License 2.0 - see the file for details.

Third-Party Licenses

• @modelcontextprotocol/sdk: MIT License
• axios: MIT License
• dotenv: BSD-2-Clause License

Full dependency licenses: npm run licenses

Acknowledgments

• Braiins Team: For exceptional mining pool infrastructure
• Anthropic: For pioneering the Model Context Protocol
• Contributors: See

Built With

• Model Context Protocol - Communication standard
• TypeScript - Type-safe JavaScript
• Node.js - Runtime environment
• Braiins Pool - Bitcoin mining pool

Citation

If you use this MCP server in research or production, please cite:

@software{braiins_pool_mcp_server,
  title = {Braiins Pool MCP Server},
  author = {Ryno Crypto Mining Services},
  year = {2024},
  url = {https://github.com/Ryno-Crypto-Mining-Services/braiins-pool-mcp-server},
  version = {1.0.0}
}

Stay Connected

• Website: rynocrypto.com
• Nostr: ryno@rynocrypto.com
• BlueSky: RynoMining
• X/Twitter: @RynoMining
• GitHub: Ryno-Crypto-Mining-Services
• LinkedIn: Company Page