bencousins22/tab-mcp

Tabcorp MCP Server

🌟 Overview

Tabcorp MCP Server is a production-ready Model Context Protocol (MCP) server that provides seamless access to Tabcorp's comprehensive betting API. With 28 specialized tools across racing, sports betting, and account management, it enables developers to build sophisticated betting applications, analysis tools, and automated systems.

Live Server: https://server.smithery.ai/@bencousins22/tab-mcp/mcp

✨ Key Features

• 🔐 Complete OAuth 2.0 Implementation - Password grant, refresh tokens, and client credentials
• 🏇 Comprehensive Racing Data - Meetings, races, form guides, runners, pools, and jackpots
• ⚽ Full Sports Coverage - Soccer, basketball, tennis, AFL, NRL with live and resulted markets
• 📊 Real-time Odds & Markets - Fixed odds, betting pools, and dividend approximations
• 🛡️ Production-Ready - Error handling, validation, rate limiting, and comprehensive testing
• 📈 High Performance - Async/await architecture with connection pooling
• 🔧 Developer-Friendly - Type hints, detailed documentation, and example code

📦 What's Included

28 Specialized Tools Across 6 Categories:

🎯 Use Cases

• Betting Bots - Automated value betting and risk management systems
• Form Analysis - Statistical racing analysis and prediction models
• Odds Comparison - Multi-market comparison and arbitrage detection
• Data Analytics - Historical trends and performance tracking
• Custom Applications - Build your own betting tools and dashboards

🚀 Quick Start

Option 1: Use Live Hosted Server (Easiest)

Connect directly to our hosted server:

from mcp.client import Client
import asyncio

async def main():
    async with Client("https://server.smithery.ai/@bencousins22/tab-mcp/mcp") as client:
        # Authenticate
        auth = await client.call_tool(
            "tab_oauth_client_credentials",
            {
                "client_id": "your_client_id",
                "client_secret": "your_client_secret"
            }
        )

        # Get next-to-go races
        races = await client.call_tool(
            "racing_get_next_to_go",
            {"access_token": auth["access_token"], "count": 5}
        )

        print(f"Found {len(races['races'])} upcoming races!")

asyncio.run(main())

Option 2: Run Locally

1. Clone and Install

git clone https://github.com/bencousins22/tab-mcp.git
cd tab-mcp
uv sync  # or: pip install -r requirements.txt

2. Configure Environment

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

3. Run Development Server

uv run dev  # Server starts on http://localhost:8081

4. Run Tests

pytest tests/unit -v
pytest tests/integration -v  # Requires API credentials

🏗️ Architecture

graph TB
    subgraph "Client Applications"
        A[Betting Bot]
        B[Form Analyzer]
        C[Odds Comparison]
    end

    subgraph "Tabcorp MCP Server"
        D[FastMCP Server]
        E[OAuth Manager]
        F[Racing Tools]
        G[Sports Tools]
        H[Error Handler]
    end

    subgraph "Tabcorp API"
        I[OAuth Endpoint]
        J[Racing API]
        K[Sports API]
    end

    A --> D
    B --> D
    C --> D
    D --> E
    D --> F
    D --> G
    D --> H
    E --> I
    F --> J
    G --> K

Key Components

• FastMCP Server: Built on Smithery's FastMCP framework with session management
• OAuth Manager: Automatic token refresh and credential management
• Tool Layer: 28 specialized tools with validation and error handling
• API Client: Async HTTP client with connection pooling and retry logic
• Error Handler: Comprehensive error parsing and user-friendly messages

📚 Documentation

For Users

• - Complete beginner's guide with installation and first API calls
• - Comprehensive documentation of all 28 tools with examples

Tutorials (Step-by-Step Projects)

• - Complete betting analysis bot with ML and risk management
• - Statistical form analysis tool with predictions
• - Odds comparison and arbitrage detection system

For Developers & DevOps

• - Production deployment procedures and rollback strategies
• - Running tests and CI/CD workflows
• - Credential management and security best practices
• - Complete DevOps infrastructure overview
• - How to contribute to the project
• - Version history and release notes

🎓 Tutorials

1. Intelligent Betting Bot

Build a complete betting bot with form analysis, value detection, and risk management:

# Analyzes form data, calculates value bets, manages bankroll
# Features: Kelly Criterion, statistical models, bet tracking
# See: TUTORIAL_BETTING_BOT.md

What you'll learn: Form analysis, value betting, risk management, database tracking, performance analytics

2. Racing Form Analyzer

Create a sophisticated form analysis tool with statistical models:

# Comprehensive form analysis with multiple performance metrics
# Features: Statistical scoring, PDF reports, visualizations
# See: TUTORIAL_FORM_ANALYSIS.md

What you'll learn: Data collection, statistical analysis, prediction models, report generation

3. Sports Odds Comparison

Build an odds comparison system with arbitrage detection:

# Multi-sport odds scanning with arbitrage finder
# Features: Real-time scanning, value detection, alerts
# See: TUTORIAL_ODDS_COMPARISON.md

What you'll learn: Arbitrage detection, value finding, odds tracking, alert systems

🔧 Configuration

Environment Variables

Create a .env file in the project root:

# OAuth Credentials (Required)
TAB_CLIENT_ID=your_client_id
TAB_CLIENT_SECRET=your_client_secret

# Personal Account (Optional - for betting features)
TAB_USERNAME=your_tab_account
TAB_PASSWORD=your_tab_password

# API Configuration
TAB_BASE_URL=https://api.beta.tab.com.au
DEFAULT_JURISDICTION=NSW

Security Note: Never commit .env to version control. The file is gitignored by default.

Session Configuration

Configure per-session settings via the MCP client:

ctx.session_config.jurisdiction = "VIC"
ctx.session_config.client_id = "custom_client_id"

🧪 Testing

Run All Tests

pytest tests/ -v

Test Categories

# Unit tests (fast, no API calls)
pytest tests/unit -v

# Integration tests (requires credentials)
pytest tests/integration -v

# Performance tests
pytest tests/performance -v

# Specific category
pytest tests/unit/oauth -v

Coverage Report

pytest --cov=src/tab_mcp --cov-report=html
# Open htmlcov/index.html

Current Coverage: 31% (baseline) | Target: 80%+

🚀 Deployment

Deploy to Smithery (Recommended)

Automated deployment via GitHub Actions:

1. Push to main branch
2. GitHub Actions runs tests
3. Manual approval in Smithery UI
4. Auto-deploy to production

See for complete deployment procedures.

Self-Hosted Deployment

# Production mode
uv run start

# Or with gunicorn
gunicorn -w 4 -k uvicorn.workers.UvicornWorker src.tab_mcp.server:app

🛡️ Security

Best Practices

• ✅ Store credentials in environment variables, never in code
• ✅ Use .env files locally (gitignored)
• ✅ Rotate credentials every 90 days
• ✅ Enable 2FA on all accounts
• ✅ Use least-privilege principle for API scopes
• ✅ Monitor access logs for suspicious activity

Vulnerability Reporting

Found a security issue? Please email security@example.com (do not open public issues).

See for complete security policies.

📊 Performance

Benchmarks

• Authentication: ~200ms (OAuth token request)
• Racing Data: ~150ms (single race with form)
• Sports Data: ~180ms (competition with matches)
• Concurrent Requests: Supports 100+ simultaneous connections
• Rate Limits: Respects Tabcorp API limits with automatic backoff

Optimization Features

• Async/await for non-blocking I/O
• Connection pooling for HTTP requests
• Token caching to reduce auth overhead
• Response caching for frequently accessed data (planned)

🤝 Contributing

We welcome contributions! Please see for:

• Development workflow and setup
• Code style guidelines (Black, Ruff)
• Testing requirements
• Pull request process
• Community guidelines

Quick Contribution Guide

# 1. Fork and clone
git clone https://github.com/YOUR_USERNAME/tab-mcp.git

# 2. Create feature branch
git checkout -b feature/amazing-feature

# 3. Make changes and test
pytest tests/ -v

# 4. Commit and push
git commit -m "Add amazing feature"
git push origin feature/amazing-feature

# 5. Open Pull Request

📝 Changelog

See for version history and release notes.

Latest Release: v1.0.0 (2024-10-29)

• ✨ Initial production release
• ✅ 28 tools across 6 categories
• ✅ Comprehensive testing suite
• ✅ Complete documentation
• ✅ CI/CD automation

📄 License

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

🙏 Acknowledgments

• Smithery - MCP server hosting platform
• FastMCP - MCP server framework
• Tabcorp - API access and documentation
• All contributors and users of this project

📞 Support

Getting Help

• 📖 Documentation: Start with
• 🐛 Bug Reports: Open an issue
• 💬 Questions: GitHub Discussions
• 📧 Email: support@example.com

Resources

• Live Server: https://server.smithery.ai/@bencousins22/tab-mcp/mcp
• Repository: https://github.com/bencousins22/tab-mcp
• Smithery Dashboard: https://smithery.ai/@bencousins22/tab-mcp
• MCP Protocol: https://modelcontextprotocol.io

⭐ Star History

If you find this project useful, please consider giving it a star! ⭐