ipstack-mcp-server

santhoshkotti/ipstack-mcp-server

3.2

If you are the rightful owner of ipstack-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

The IPStack MCP Server provides IP geolocation services using the IPStack API, operating in stdio transport mode for MCP clients.

Tools
3
Resources
0
Prompts
0

IPStack MCP Server

A Model Context Protocol (MCP) server that provides IP geolocation services using the IPStack API. This server runs in stdio transport mode for MCP clients and provides comprehensive IP geolocation data.

Features

  • IP Geolocation Lookup: Get detailed location information for any IP address
  • Bulk IP Lookup: Look up multiple IP addresses at once
  • Current IP Info: Get geolocation data for the current public IP
  • MCP Compatible: Runs in stdio mode for Model Context Protocol clients
  • Docker Support: Optional Docker deployment for specialized use cases
  • Comprehensive Resources: Provides information about supported fields and API usage

Prerequisites

  • Python 3.11+
  • IPStack API key (free tier available at ipstack.com)
  • Docker (optional, for containerized deployment)

Local Development Setup

1. Get an IPStack API Key

  1. Sign up at ipstack.com
  2. Get your free API key from the dashboard
  3. Free plan includes 1,000 requests/month

2. Environment Configuration

Create a .env file in the project root:

# IPStack API Configuration
IPSTACK_API_KEY=your_actual_api_key_here

# MCP Server Configuration (optional - defaults to stdio)
MCP_SERVER_MODE=stdio

⚠️ Important for Local Developers:

  • You must add your IPSTACK_API_KEY to the .env file when running locally without Docker
  • Never commit your actual API key to version control
  • The .env file is already in .gitignore to prevent accidental commits

3. Install Dependencies

# Create virtual environment (recommended)
python -m venv venv
source venv/bin/activate  # Linux/macOS
# or
venv\Scripts\activate     # Windows

# Install dependencies
pip install -r requirements.txt

4. Run the Server

# The server always runs in stdio mode
python server.py

Testing with MCP Inspector

For development and testing, use the MCP Inspector:

npx @modelcontextprotocol/inspector python server.py

This opens a web interface where you can test all MCP tools and resources.

Available Tools

lookup_ip

Look up geolocation information for a single IP address.

Parameters:

  • ip_address (required): The IP address to lookup
  • fields (optional): Comma-separated list of fields to return
  • language (optional): Language code (default: "en")

Example:

{
  "ip_address": "8.8.8.8",
  "fields": "country_name,city,latitude,longitude",
  "language": "en"
}

lookup_multiple_ips

Look up geolocation information for multiple IP addresses.

Parameters:

  • ip_addresses (required): Comma-separated list of IP addresses
  • fields (optional): Comma-separated list of fields to return
  • language (optional): Language code (default: "en")

Example:

{
  "ip_addresses": "8.8.8.8,1.1.1.1,208.67.222.222",
  "fields": "country_name,city",
  "language": "en"
}

get_current_ip_info

Get geolocation information for the current public IP address.

Parameters:

  • fields (optional): Comma-separated list of fields to return
  • language (optional): Language code (default: "en")

Example:

{
  "fields": "country_name,region_name,city,latitude,longitude",
  "language": "en"
}

Available Resources

ipstack://supported-fields

Returns information about all supported IPStack API fields and their descriptions.

ipstack://usage-info

Returns information about IPStack API usage limits and plan features.

Supported Fields

The IPStack API supports various fields depending on your plan:

Free Plan Fields

  • ip, type, continent_code, continent_name
  • country_code, country_name, region_code, region_name
  • city, zip, latitude, longitude

Standard Plan+ Fields

  • time_zone - Time zone information
  • currency - Currency information

Professional Plan+ Fields

  • connection - ISP and connection details
  • security - Security and threat information

Docker Deployment (Optional)

The server is primarily designed for stdio/MCP usage, but Docker deployment is available for specialized use cases.

Building and Running with Docker

# Build the image
docker build -t ipstack-mcp-server .

# Run with API key as environment variable
docker run -i --rm -e IPSTACK_API_KEY=your_actual_api_key_here ipstack-mcp-server

Note: Docker deployment runs the server in stdio mode, same as local development.

Configuration

Environment Variables

VariableDescriptionRequiredDefault
IPSTACK_API_KEYYour IPStack API keyYesNone

For Local Development: Add IPSTACK_API_KEY=your_key to your .env file.

For Docker: Pass as environment variable: -e IPSTACK_API_KEY=your_key

Development

Project Structure

ipstack-mcp-server/
├── server.py               # Main server code
├── requirements.txt        # Python dependencies  
├── Dockerfile             # Docker configuration
├── docker-compose.yml     # Docker Compose configuration
├── .env                   # Environment variables (create this!)
├── .gitignore            # Git ignore rules
├── .dockerignore         # Docker ignore rules
└── README.md             # This file

Local Development Workflow

  1. Clone/Download the project

  2. Create and configure .env file:

    # Create .env file in project root
echo "IPSTACK_API_KEY=your_actual_api_key_here" > .env

  3. Set up Python environment:

    python -m venv venv
source venv/bin/activate  # Linux/macOS
# or  
venv\Scripts\activate     # Windows

  4. Install dependencies:

    pip install -r requirements.txt

  5. Run the server:

    python server.py

Testing with MCP Inspector

The MCP Inspector is essential for testing your MCP server:

npx @modelcontextprotocol/inspector python server.py

This provides a web interface to:

  • Test all available tools
  • View resource content
  • Debug MCP communication
  • Validate server responses

Important Notes for Developers

  • ⚠️ Always use the .env file for local development - The server reads IPSTACK_API_KEY from environment variables
  • 🔒 Never commit your API key - The .env file is in .gitignore
  • 📝 Server runs in stdio mode only - Optimized for MCP client communication
  • 🧪 Use MCP Inspector for testing - Essential tool for MCP development

Docker Deployment

Building the Image

docker build -t ipstack-mcp-server .

Running with Docker

# Run with API key passed as environment variable
docker run -i --rm -e IPSTACK_API_KEY=your_actual_api_key_here ipstack-mcp-server

Note: The Docker container runs in stdio mode for MCP compatibility.

Using Docker Compose (Alternative)

# Set environment variable first
export IPSTACK_API_KEY=your_actual_api_key_here

# Start service
docker-compose up --build

# Stop service  
docker-compose down

API Rate Limits

Be aware of IPStack API rate limits based on your plan:

  • Free Plan: 1,000 requests/month
  • Standard Plan: 10,000 requests/month
  • Professional Plan: 100,000 requests/month

Error Handling

The server includes comprehensive error handling:

  • Invalid API Key: Returns clear error message
  • Rate Limit Exceeded: Passes through IPStack error information
  • Invalid IP Address: Returns validation error
  • Network Issues: Handles connection timeouts and failures

Security Considerations

  • Keep your IPStack API key secure and never commit it to version control
  • Use environment variables or secure secret management for production
  • The HTTP server should be run behind a reverse proxy (nginx, Apache) in production
  • Consider implementing authentication for the HTTP endpoint in production

Contributing

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

License

This project is open source and available under the MIT License.

Troubleshooting

Common Issues

  1. "IPSTACK_API_KEY environment variable is required"

    • Local Development: Make sure you have IPSTACK_API_KEY=your_key in your .env file
    • Docker: Pass the API key with -e IPSTACK_API_KEY=your_key

  2. "IPStack API Error: Invalid API key"

    • Verify your API key is correct and active at ipstack.com
    • Make sure there are no extra spaces in your .env file

  3. "Failed to fetch IP information: timeout"

    • Check your network connection and IPStack service status
    • Verify your API key hasn't exceeded rate limits

  4. MCP Inspector not connecting

    • Ensure you're running: npx @modelcontextprotocol/inspector python server.py
    • Check that Python dependencies are installed
    • Verify the .env file exists with your API key

  5. Server not starting

    • Check Python version (requires 3.11+)
    • Ensure all dependencies are installed: pip install -r requirements.txt
    • Verify .env file is in the project root directory

Debug Mode

To enable debug logging, modify the server.py logging level:

logging.basicConfig(level=logging.DEBUG)

Validating Your Setup

Test your setup with a simple API call:

# After starting the server with MCP Inspector
# Use the lookup_ip tool with:
# ip_address: "8.8.8.8"
# This should return Google's DNS server location info

Support

For issues related to: