Parking MCP Server

A Model Context Protocol (MCP) server for parking system that provides tools to query user information, parking plans, orders, and parking space status.

Features

• 🔍 get_user_info - Query user basic information, parking habits, common parking lots
• 📅 get_user_parking_plans - Query today's parking plans for a specific user
• 🎫 get_user_orders - Query parking orders (history + current) for a user
• 🅿️ get_parking_space_status - Query parking space occupancy status

Installation

Install from PyPI (Recommended)

pip install parking-mcp-server

The package includes a sample SQLite database with parking data, so it works out-of-the-box!

Install from Source

git clone https://github.com/yourusername/parking-mcp-server.git
cd parking-mcp-server
pip install -e .

Prerequisites

• Python 3.8+
• MCP-compatible client (Claude Desktop, Cursor, etc.)
• (Optional) Your own SQLite database if you want to use custom data

Quick Start

1. Install and Run (Out-of-the-Box)

The package includes a sample SQLite database, so you can start immediately:

# Install from PyPI
pip install parking-mcp-server

# Run the server (uses included sample database)
parking-mcp-server

# The server will automatically use the packaged parking.db

2. Use Your Own Database (Optional)

If you have your own parking database, you can use it instead:

Method A: Environment Variable

export PARKING_DB_PATH=/path/to/your/parking.db
parking-mcp-server

Method B: Command Line Argument

parking-mcp-server --db-path /path/to/your/parking.db

Method C: Place in Current Directory

cd /path/to/your/db
cp /path/to/your/parking.db .
parking-mcp-server

3. Configure MCP Client

Once the server is running, configure your MCP client:

Claude Desktop:

{
  "mcpServers": {
    "parking-system": {
      "command": "parking-mcp-server",
      "env": {
        "PARKING_DB_PATH": "/path/to/your/parking.db"
      }
    }
  }
}

Without environment variable (uses packaged or default DB):

{
  "mcpServers": {
    "parking-system": {
      "command": "parking-mcp-server"
    }
  }
}

4. Configure MCP Client

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (Mac) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "parking-system": {
      "command": "parking-mcp-server",
      "env": {
        "PARKING_DB_PATH": "/path/to/your/parking.db"
      },
      "transport": "stdio"
    }
  }
}

Cursor

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "parking-system": {
      "command": "parking-mcp-server",
      "env": {
        "PARKING_DB_PATH": "/path/to/your/parking.db"
      }
    }
  }
}

Available Tools

get_user_info

Query user basic information including profile, parking habits, and preferences.

Parameters:

• user_id (integer, required): The ID of the user to query

Example in MCP client:

What's the parking habit of user 10001?

get_user_parking_plans

Query today's parking plans for a specific user.

Parameters:

• user_id (integer, required): The ID of the user to query

Example in MCP client:

Show me today's parking plans for user 10001

get_user_orders

Query parking orders (both historical and current) for a user.

Parameters:

• user_id (integer, required): The ID of the user to query

Example in MCP client:

What are the recent parking orders for user 10001?

get_parking_space_status

Query parking space occupancy status across all parking lots or a specific one.

Parameters:

• park_id (string, optional): Specific parking lot ID to query. If omitted, returns all parking lots.

Example in MCP client:

What's the current occupancy status of parking lot TCC0001?
Show me the status of all parking spaces

Database Schema

The package includes a sample database with the following tables:

Sample Data Included

• 3,000 users with various parking habits (Pendulum, Random, Task-driven, Nail users)
• 1,000 parking spaces across 20 parking lots
• 9,413 parking plans for simulation
• 2,917 parking orders (completed and active)

Table Structure

t_users

• user_id (INTEGER, PRIMARY KEY)
• user_name (TEXT)
• plate_number (TEXT)
• phone_number (TEXT)
• payment_habit (TEXT) - Forgetting, Watching, Busy, Malicious
• parking_habit (TEXT) - Pendulum, Random, Task-driven, Nail user
• working_time (TEXT) - For pendulum users
• offwork_time (TEXT) - For pendulum users
• common_park_ids (TEXT) - Comma-separated parking lot IDs
• common_park_label (TEXT) - Comma-separated zone types
• is_wechat_bound (INTEGER) - 0 or 1
• create_time (TEXT)

t_parking_space

• space_id (TEXT, PRIMARY KEY) - Format: T0001
• park_id (TEXT) - Format: TCC0001 to TCC0020
• zone_type (TEXT) - Residential, Office, Commercial, Entertainment, Street, Special
• is_used (INTEGER) - 0 (available) or 1 (occupied)
• used_time (TEXT) - Timestamp of last status change
• create_time (TEXT)

t_will_parking (Parking Plans)

• id (INTEGER, PRIMARY KEY)
• user_id (INTEGER)
• parking_in_time (TEXT) - Predicted entry time
• parking_out_time (TEXT) - Predicted exit time
• target_zones (TEXT) - Target parking zones
• status (INTEGER) - 0=pending, 1=active, 2=completed, -1=cancelled
• plan_date (TEXT) - Date of the plan

t_parking_orders (Real Orders)

• order_id (TEXT, PRIMARY KEY) - UUID
• user_id (INTEGER)
• space_id (TEXT) - Actual occupied space
• park_id (TEXT) - Parking lot ID
• start_time (TEXT) - Actual entry time
• end_time (TEXT) - Actual exit time (NULL if still active)

For Developers

If you want to generate your own data instead of using the sample database:

# Clone the data generation scripts from the repository
git clone https://github.com/yourusername/parking-mcp-server.git
cd parking-mcp-server

# Generate parking spaces
python generate_mock_spaces.py 1000

# Generate users
python generate_mock_users.py 3000

# Generate parking plans and run simulation
python simulation_engine.py

Then configure the MCP server to use your generated database:

export PARKING_DB_PATH=./parking.db
parking-mcp-server

Development

Setup Development Environment

git clone https://github.com/yourusername/parking-mcp-server.git
cd parking-mcp-server
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -e ".[dev]"

Running Tests

pytest

Building Distribution

# Build wheel and source distribution
python -m build

# Upload to PyPI (requires credentials)
python -m twine upload dist/*

Environment Variables

• PARKING_DB_PATH: Path to SQLite database file (default: parking.db)

Troubleshooting

Database not found error

Make sure the database file exists and the path is correctly set:

export PARKING_DB_PATH=/absolute/path/to/parking.db

MCP client not connecting

1. Check that the server starts without errors
2. Verify the command path in MCP client configuration
3. Ensure the database is accessible
4. Check logs for any error messages

Permission errors

Ensure the database file has appropriate read permissions:

chmod 644 parking.db

License

MIT License - see LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

If you encounter any issues or have questions:

• Open an issue on GitHub: https://github.com/yourusername/parking-mcp-server/issues
• Check the documentation above
• Ensure all prerequisites are met