Skip to main content
Glama

Owner avatar beijing-car-quota-draw

by coldfire-x
GitHub
Python
MIT License
  • Apple
  • Linux
OverviewInspectNewEndpointsSchemaRelated ServersReviewsScore
Need Help?View Source CodeReport Issue

Beijing Car Quota Lottery MCP Server

An MCP (Model Context Protocol) server that provides AI agents with the ability to query Beijing car quota lottery results. This server scrapes data from the Beijing Transportation Commission website and exposes search capabilities through a standardized MCP interface.

Features

  • 🔍 Smart Search: Search by application code (申请编码) or partial ID number

  • 📄 PDF Processing: Automatically parses different PDF formats (waiting lists and score rankings)

  • 🌐 Web Scraping: Scrapes latest data from Beijing Transportation Commission website

  • 🤖 AI Integration: Exposes functionality as MCP tools for AI agents like Claude, Cursor, etc.

  • 💾 Data Persistence: Stores processed data locally with fast indexing

  • 📊 Statistics: Provides insights into loaded data and search results

Tech Stack

  • Language: Python 3.9+

  • Web Framework: FastAPI

  • MCP Framework: fastapi-mcp

  • PDF Processing: pdfplumber

  • Web Scraping: crawl4ai

  • Dependency Management: uv

Installation

Prerequisites

  • Python 3.9 or higher

  • uv (recommended) or pip

Using uv (Recommended)

# Clone the repository git clone <repository-url> cd bjhjyd-mcp # Install dependencies uv sync # Activate virtual environment source .venv/bin/activate # On Windows: .venv\Scripts\activate

Using pip

# Clone the repository git clone <repository-url> cd bjhjyd-mcp # Create virtual environment python -m venv venv source venv/bin/activate # On Windows: venv\Scripts\activate # Install dependencies pip install -e .

Quick Start

1. Start the MCP Server

# Using the main module python -m bjhjyd_mcp.main # Or with custom settings python -m bjhjyd_mcp.main --host 0.0.0.0 --port 8080 --log-level DEBUG

The server will start at http://127.0.0.1:8000 by default.

2. Access the API

3. Configure AI Clients

For Cursor IDE

  1. Go to Settings → MCP → Add new MCP server

  2. Add this configuration:

{ "mcpServers": { "Beijing Car Quota": { "url": "http://127.0.0.1:8000/mcp" } } }

For Claude Desktop

  1. Install mcp-proxy: uv tool install mcp-proxy

  2. Configure in claude_desktop_config.json:

{ "mcpServers": { "Beijing Car Quota": { "command": "mcp-proxy", "args": ["http://127.0.0.1:8000/mcp"] } } }

Available MCP Tools

The server exposes the following tools for AI agents:

1. search_by_application_code

Search for quota results by application code (申请编码).

Parameters:

  • application_code (string): The application code to search for

Example:

{ "application_code": "1437100439239" }

2. search_by_id_number

Search for quota results by partial ID number (first 6 and last 4 digits).

Parameters:

  • id_prefix (string): First 6 digits of ID number

  • id_suffix (string): Last 4 digits of ID number

Example:

{ "id_prefix": "110228", "id_suffix": "1240" }

3. get_data_statistics

Get statistics about loaded quota data.

Returns: Information about total files, entries, and data breakdown.

4. refresh_data

Refresh quota data by scraping the latest PDFs from the website.

Parameters:

  • max_pages (integer, optional): Maximum pages to scrape (default: 5)

5. list_data_files

List all loaded quota data files with metadata.

6. health_check

Check server health and status.

Data Formats

The server handles two types of PDF formats from the Beijing Transportation Commission:

1. Waiting List (轮候序号列表)

  • Fields: 序号, 申请编码, 轮候时间

  • Purpose: Time-based ordering for quota applications

2. Score Ranking (积分排序入围名单)

  • Fields: 序号, 申请编码, 姓名, 身份证号, 家庭代际数, 积分, 注册时间

  • Purpose: Score-based ranking with personal information

  • Privacy: ID numbers are masked (e.g., 110228********1240)

Development

Project Structure

src/ ├── bjhjyd_mcp/ │ ├── __init__.py │ ├── main.py # Entry point │ ├── models/ # Data models │ │ ├── quota_result.py │ ├── parsers/ # PDF parsing │ │ ├── pdf_parser.py │ ├── scrapers/ # Web scraping │ │ ├── web_scraper.py │ ├── server/ # MCP server │ │ ├── mcp_server.py │ ├── storage/ # Data storage │ │ ├── data_store.py │ └── utils/ # Utilities │ ├── logging_config.py └── tests/ ├── unit/ └── integration/

Running Tests

# Run all tests pytest # Run with coverage pytest --cov=src --cov-report=html # Run specific test file pytest src/tests/unit/test_pdf_parser.py

Code Quality

# Format code black src/ # Sort imports isort src/ # Type checking mypy src/ # Linting flake8 src/

Configuration

Environment Variables

  • LOG_LEVEL: Logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL)

  • DATA_DIR: Directory for storing processed data

  • DOWNLOADS_DIR: Directory for downloaded PDF files

Command Line Options

python -m bjhjyd_mcp.main --help

API Examples

Direct API Usage

import httpx # Search by application code response = httpx.post( "http://127.0.0.1:8000/search/application-code", json={"application_code": "1437100439239"} ) print(response.json()) # Get statistics response = httpx.get("http://127.0.0.1:8000/data/statistics") print(response.json())

Using with AI Agents

Once configured, AI agents can use natural language to query the data:

  • "Check if application code 1437100439239 won the lottery"

  • "Search for ID number starting with 110228 and ending with 1240"

  • "Show me the latest quota lottery statistics"

  • "Refresh the data with new PDFs from the website"

Troubleshooting

Common Issues

  1. Server won't start

    • Check if port 8000 is available

    • Verify all dependencies are installed

    • Check logs for specific error messages

  2. No data found

    • Run refresh_data tool to scrape latest PDFs

    • Check if example PDFs exist in the examples/ directory

    • Verify network connectivity for web scraping

  3. PDF parsing errors

    • Check PDF format compatibility

    • Verify PDF files are not corrupted

    • Review parsing logs for specific issues

Logging

Enable debug logging for detailed information:

python -m bjhjyd_mcp.main --log-level DEBUG --log-file logs/server.log

Contributing

  1. Fork the repository

  2. Create a feature branch

  3. Make your changes

  4. Add tests for new functionality

  5. Run the test suite

  6. Submit a pull request

License

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

Disclaimer

This tool is for educational and research purposes only. Please respect the Beijing Transportation Commission's terms of service and rate limits when scraping their website.

This server cannot be installed

-
security - not tested
A
license - permissive license
-
quality - not tested

How are these scores calculated?

hybrid server

The server is able to function both locally and remotely, depending on the configuration or use case.

Owner avatar beijing-car-quota-draw

  1. Features
    1. Tech Stack
      1. Installation
        1. Prerequisites
        2. Using uv (Recommended)
        3. Using pip
      2. Quick Start
        1. 1. Start the MCP Server
        2. 2. Access the API
        3. 3. Configure AI Clients
      3. Available MCP Tools
        1. 1. search_by_application_code
        2. 2. search_by_id_number
        3. 3. get_data_statistics
        4. 4. refresh_data
        5. 5. list_data_files
        6. 6. health_check
      4. Data Formats
        1. 1. Waiting List (轮候序号列表)
        2. 2. Score Ranking (积分排序入围名单)
      5. Development
        1. Project Structure
        2. Running Tests
        3. Code Quality
      6. Configuration
        1. Environment Variables
        2. Command Line Options
      7. API Examples
        1. Direct API Usage
        2. Using with AI Agents
      8. Troubleshooting
        1. Common Issues
        2. Logging
      9. Contributing
        1. License
          1. Disclaimer

            Related MCP Servers

            View all related MCP servers

            New MCP Servers

            MCP directory API

            We provide all the information about MCP servers via our MCP API.

            curl -X GET 'https://glama.ai/api/mcp/v1/servers/coldfire-x/beijing-car-quota-draw-mcp'

            If you have feedback or need assistance with the MCP directory API, please join our Discord server