SocialMapper MCP Server

A Model Context Protocol (MCP) server that provides AI assistants with access to SocialMapper's spatial analysis capabilities.

Overview

SocialMapper is a powerful spatial analysis platform that helps understand community accessibility patterns, demographic distributions, and Points of Interest (POI) relationships. This MCP server exposes SocialMapper's functionality to AI assistants like Claude Code.

Features

🏢 POI Analysis

• Discover Points of Interest within travel time constraints
• Support for 10+ POI categories (libraries, hospitals, schools, parks, etc.)
• Travel time analysis with walking, biking, and driving modes

📊 Census Integration

• Access to comprehensive US Census demographic data
• Block group and ZCTA geographic levels
• Population, income, housing, and education variables

🎬 Demo Scenarios

• Pre-built analysis scenarios for common use cases
• Urban equity analysis
• Food desert identification
• Healthcare accessibility studies

📈 Results Management

• Track analysis progress in real-time
• Export results in multiple formats (CSV, GeoJSON, Parquet)
• Interactive map visualizations

Installation

Prerequisites

1. Python 3.11+ with uv package manager
2. SocialMapper API server running locally
3. Census API Key (free from api.census.gov)

Quick Start

1. Install the MCP server package:

   npm install -g @socialmapper/mcp-server

2. Start the SocialMapper API server:

   # Navigate to your SocialMapper installation
   cd path/to/socialmapper/socialmapper-api
      
   # Set environment variables
   export SOCIALMAPPER_API_MCP_ENABLED=true
   export SOCIALMAPPER_API_CENSUS_API_KEY=your_census_api_key
      
   # Start the server
   uv run uvicorn api_server.main:app --host 0.0.0.0 --port 8000

3. Add to Claude Code:

   claude mcp add socialmapper-local --scope user -- npx @socialmapper/mcp-server

Available Tools

Core Analysis

• analyze_location - Submit location-based accessibility analysis
• get_analysis_status - Check analysis job progress
• get_results - Retrieve completed analysis results

Metadata

• get_poi_types - List available POI categories and types
• get_census_variables - Get available demographic variables

Demo & Examples

• get_demo_scenarios - View available demo analyses
• run_demo_scenario - Execute pre-built demo scenarios

Results Management

• list_results - List all completed analyses

Usage Examples

Once connected to Claude Code, you can use natural language:

• "What types of places can SocialMapper analyze?"
• "Analyze libraries within 15 minutes walking distance of downtown Denver"
• "Show me available demographic variables for census analysis"
• "Run a demo scenario to see how accessibility analysis works"
• "Check the status of my analysis job"
• "Show me the results of my completed analysis"

Configuration

Environment Variables

Set these in your SocialMapper API server environment:

# Required
SOCIALMAPPER_API_MCP_ENABLED=true
SOCIALMAPPER_API_CENSUS_API_KEY=your_api_key

# Optional
SOCIALMAPPER_API_MCP_AUTH_ENABLED=false
SOCIALMAPPER_API_MCP_RATE_LIMIT_PER_MINUTE=60
SOCIALMAPPER_API_MCP_TOOL_TIMEOUT=30

Advanced Configuration

For custom server URLs or advanced settings, see the full documentation.

Troubleshooting

Common Issues

1. "Server not responding"

   • Ensure SocialMapper API server is running on localhost:8000
   • Check that MCP is enabled in server configuration

2. "Census API errors"

   • Verify your Census API key is valid
   • Check the key is properly set in environment variables

3. "Tool not found"

   • Restart Claude Code after adding the MCP server
   • Verify the server was added with correct scope

Debug Mode

Run with debug logging:

SOCIALMAPPER_API_LOG_LEVEL=DEBUG uv run uvicorn api_server.main:app --reload

Development

Local Development

1. Clone the SocialMapper repository
2. Navigate to socialmapper-api/
3. Install dependencies: uv pip install -e .
4. Start development server: uv run uvicorn api_server.main:app --reload

Contributing

See CONTRIBUTING.md for development guidelines.

License

MIT License - see LICENSE file.

Support

• 📚 Documentation
• 🐛 Issues
• 💬 Discussions

Related

• SocialMapper Core - Main spatial analysis library
• Model Context Protocol - Open standard for AI tool integration
• Claude Code - AI-powered development assistant