outscraper-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Development Commands

Testing:

pytest                              # Run all tests
pytest tests/test_server.py         # Run specific test file
pytest -v                          # Verbose output
pytest tests/test_integration.py    # Integration tests

Linting and Code Quality:

black outscraper_mcp/              # Format code
flake8 outscraper_mcp/              # Lint code  
mypy outscraper_mcp/                # Type checking

Package Management:

uv sync                             # Install dependencies
uv add <package>                    # Add new dependency
uv pip install -e .                    # Install in development mode

Running the Server:

# Development with FastMCP inspector
fastmcp dev outscraper_mcp/server.py

# Production (stdio transport)
python -m outscraper_mcp
outscraper-mcp                      # Via entry point

# HTTP transport for testing
python -c "from outscraper_mcp import mcp; mcp.run(transport='streamable-http', host='127.0.0.1', port=8000)"

Architecture

MCP Server Structure:

• Built using FastMCP framework for simplified MCP server development
• Two main tools: google_maps_search and google_maps_reviews
• Outscraper API client with retry logic and error handling
• Supports both synchronous and asynchronous API operations

Key Components:

• outscraper_mcp/server.py - Main MCP server implementation with tools
• outscraper_mcp/__init__.py - Package entry point and main() function
• OutscraperClient class - Handles API communication with retry logic
• Tool validation and response formatting for optimal Claude integration

API Integration:

• Uses Outscraper API v3 endpoints (/maps/search-v3, /maps/reviews-v3)
• Automatic async handling for large requests (>10 queries, >499 reviews)
• Request retry strategy for robust API communication
• Environment variable OUTSCRAPER_API_KEY required for operation