ice-locator-mcp

🔍 ICE Locator MCP Server

MCP Compatible Python 3.10+ License: MIT Tests Coverage

Empower AI agents with ICE detainee location capabilities

Connect your LLM applications to the U.S. Immigration and Customs Enforcement (ICE) Online Detainee Locator System through a standardized Model Context Protocol (MCP) interface.

✨ Features

🚀 Quick Start

Installation

# Install via pip
pip install ice-locator-mcp

# Or install from source
git clone https://github.com/trose/ice-locator-mcp.git
cd ice-locator-mcp
pip install -e .

Configuration for Claude Desktop

Add to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "ice-locator": {
      "command": "ice-locator-mcp",
      "args": []
    }
  }
}

Configuration for Cursor IDE

Add to your Cursor settings:

{
  "mcp.servers": [
    {
      "name": "ice-locator",
      "command": "ice-locator-mcp"
    }
  ]
}

📖 Usage Examples

# Search by name and personal information
result = await search_detainee_by_name(
    first_name="John",
    last_name="Doe", 
    date_of_birth="1990-01-15",
    country_of_birth="Mexico"
)

# AI-powered natural language search
result = await smart_detainee_search(
    query="Find Maria Rodriguez from Guatemala born around 1985"
)

Bulk Search Operations

# Search multiple detainees simultaneously
result = await bulk_search_detainees(
    search_requests=[
        {
            "first_name": "John",
            "last_name": "Doe",
            "date_of_birth": "1990-01-15", 
            "country_of_birth": "Mexico"
        },
        {
            "alien_number": "A123456789"
        }
    ],
    max_concurrent=3
)

# Create comprehensive reports for legal use
result = await generate_search_report(
    search_criteria={"first_name": "John", "last_name": "Doe"},
    results=[...],
    report_type="legal",
    format="markdown"
)

🎯 Use Cases

Family Members

Advocacy Organizations

AI Assistants

🛡️ Anti-Detection Features

IP Rotation & Proxy Management

Behavioral Simulation

Browser-Based Simulation (Playwright)

Request Obfuscation

🔒 Privacy-First Analytics & Monitoring

MCPcat Analytics Integration

This MCP server includes optional integration with MCPcat, an analytics platform specifically designed for MCP servers. Your privacy and security are our top priority:

Automatic Data Redaction 🛡️

What Data is Collected 📊

What Data is NOT Collected ❌

Privacy Controls 🔐

# Disable analytics completely
export ICE_LOCATOR_ANALYTICS_ENABLED=false

Benefits of Analytics ✨

Transparency Commitment 📋

🔒 Security First: MCPcat is designed by privacy advocates for privacy advocates. All data is encrypted in transit and at rest, with comprehensive redaction ensuring sensitive information never leaves your environment.

⚙️ Configuration

Environment Variables

# Proxy settings
export ICE_LOCATOR_PROXY_ENABLED=true
export ICE_LOCATOR_PROXY_ROTATION_INTERVAL=300

# Rate limiting
export ICE_LOCATOR_REQUESTS_PER_MINUTE=10
export ICE_LOCATOR_TIMEOUT=30

# Caching
export ICE_LOCATOR_CACHE_ENABLED=true
export ICE_LOCATOR_CACHE_TTL=3600
export ICE_LOCATOR_CACHE_DIR=~/.cache/ice-locator-mcp

# Logging
export ICE_LOCATOR_LOG_LEVEL=INFO
export ICE_LOCATOR_LOG_DIR=~/.logs/ice-locator-mcp

Configuration File

Create config.yml in your working directory:

proxy:
  enabled: true
  rotation_interval: 300
  max_requests_per_proxy: 10

search:
  timeout: 30
  max_retries: 3
  fuzzy_threshold: 0.7
  human_delays: true

cache:
  enabled: true
  ttl: 3600
  backend: diskcache

security:
  log_sensitive_data: false
  anonymize_logs: true
  encrypt_cache: false

🧪 Development

Setup Development Environment

# Clone repository
git clone https://github.com/yourusername/ice-locator-mcp.git
cd ice-locator-mcp

# Install development dependencies
pip install -e ".[dev]"

# Install pre-commit hooks
pre-commit install

Running Tests

# Run all tests
pytest

# Run with coverage
pytest --cov=ice_locator_mcp --cov-report=html

# Run specific test categories
pytest tests/unit/         # Unit tests only
pytest tests/integration/  # Integration tests only

Code Quality

# Lint code
ruff check src/ tests/
ruff format src/ tests/

# Type checking
mypy src/ice_locator_mcp/

# Security scanning
bandit -r src/
safety check

📚 API Reference

Available Tools

Tool Description Parameters
search_detainee_by_name Search by personal information first_name, last_name, date_of_birth, country_of_birth
search_detainee_by_alien_number Search by A-number alien_number
smart_detainee_search AI-powered natural language search query, context
bulk_search_detainees Multiple concurrent searches search_requests, max_concurrent
generate_search_report Create comprehensive reports search_criteria, results, report_type

Response Schema

{
  "status": "found|not_found|error|partial",
  "results": [
    {
      "alien_number": "A123456789",
      "name": "John Doe",
      "date_of_birth": "1990-01-15",
      "country_of_birth": "Mexico",
      "facility_name": "Processing Center",
      "facility_location": "City, State", 
      "custody_status": "In Custody",
      "last_updated": "2024-01-15T10:30:00Z",
      "confidence_score": 0.95
    }
  ],
  "search_metadata": {
    "search_date": "2024-01-15T10:30:00Z",
    "total_results": 1,
    "processing_time_ms": 1250,
    "corrections_applied": [],
    "suggestions": []
  },
  "user_guidance": {
    "next_steps": ["Contact facility", "Verify information"],
    "legal_resources": [],
    "family_resources": []
  }
}

🔒 Privacy & Security

Data Handling

Responsible Usage

Security Features

MCPcat Privacy Assurance

📜 Legal & Ethical Considerations

Intended Use

This tool is designed for legitimate purposes including:

Restrictions

Disclaimer

This software is provided for educational and legitimate use purposes. Users are responsible for ensuring their use complies with all applicable laws and regulations.

🤝 Contributing

We welcome contributions! Please see our Contributing Guidelines for details.

Development Process

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Add tests and documentation
  5. Submit a pull request

Code of Conduct

Please read our Code of Conduct before contributing.

📋 License

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

🆘 Support

⚠️ Important Notice: This is an independent project not affiliated with ICE or any government agency. Use responsibly and in compliance with all applicable laws.

This site is open source. Improve this page.