nadlan-mcp/DEPLOYMENT.md

Deployment Guide

This guide covers deploying Nadlan-MCP as an MCP server for AI agents.

Prerequisites

• Python 3.10 or higher
• pip package manager
• MCP-compatible client (Claude Desktop, etc.)

Installation

1. Clone and Setup

git clone <repository-url>
cd nadlan-mcp
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt

2. Verify Installation

# Test the library
python -c "from nadlan_mcp.govmap import GovmapClient; print('✓ Installation successful')"

# Test the MCP server
python run_fastmcp_server.py

Deployment Options

Option 1: Claude Desktop (Recommended)

Add to your Claude Desktop MCP configuration file:

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

{
  "mcpServers": {
    "nadlan-mcp": {
      "command": "python",
      "args": ["/absolute/path/to/nadlan-mcp/run_fastmcp_server.py"],
      "env": {}
    }
  }
}

Important: Use absolute paths, not relative paths.

Restart Claude Desktop to load the server.

Option 2: Custom MCP Client

Use stdio transport to connect:

import asyncio
from mcp.client.stdio import stdio_client

async def main():
    async with stdio_client([
        "python",
        "/path/to/nadlan-mcp/run_fastmcp_server.py"
    ]) as client:
        # List available tools
        result = await client.list_tools()
        print("Tools:", [t.name for t in result.tools])

        # Call a tool
        result = await client.call_tool(
            "find_recent_deals_for_address",
            {"address": "רוטשילד 1 תל אביב", "years_back": 2}
        )
        print(result)

asyncio.run(main())

Option 3: Direct Python Usage

Use as a library without MCP:

from nadlan_mcp.govmap import GovmapClient

client = GovmapClient()
deals = client.find_recent_deals_for_address("תל אביב רוטשילד 1", years_back=2)
print(f"Found {len(deals)} deals")

Option 4: Cloud Deployment (HTTP)

Deploy Nadlan-MCP as an HTTP service to cloud platforms like Render, Railway, or using Docker.

Prerequisites

• Docker installed (for Docker deployment)
• Render/Railway account (for cloud deployment)
• Git repository (for cloud deployment)

4.1: Render Deployment

Step 1: Push your code to a Git repository (GitHub, GitLab, etc.)

Step 2: Create a new Web Service on Render:

• Go to https://dashboard.render.com
• Click "New +" → "Web Service"
• Connect your Git repository
• Configure:
  • Name: nadlan-mcp (or your preferred name)
  • Environment: Docker
  • Region: Choose closest to your users
  • Branch: main (or your default branch)
  • Build Command: (leave empty - Docker handles this)
  • Start Command: (leave empty - Docker CMD is used)

Step 3: Configure Environment Variables (optional):

In Render dashboard, add environment variables:

GOVMAP_MAX_RETRIES=3
GOVMAP_REQUESTS_PER_SECOND=5.0
GOVMAP_DEFAULT_YEARS_BACK=2

Step 4: Deploy

• Click "Create Web Service"
• Render will automatically build and deploy your Docker container
• Wait for deployment to complete (~2-5 minutes)

Step 5: Access Your Service

• Your service will be available at: https://your-service-name.onrender.com
• MCP endpoint: https://your-service-name.onrender.com/mcp
• Health check: https://your-service-name.onrender.com/health

Important Notes:

• Render's free tier may have cold starts (delays when service is idle)
• For production, use a paid plan for better performance
• The HTTP server runs on the port specified by Render's PORT environment variable

4.2: Docker Deployment

Build the Docker Image:

docker build -t nadlan-mcp .

Run Locally:

# Run on default port 8000
docker run -p 8000:8000 nadlan-mcp

# Run on custom port
docker run -p 8080:8080 -e PORT=8080 nadlan-mcp

# Run with environment variables
docker run -p 8000:8000 \
  -e GOVMAP_MAX_RETRIES=5 \
  -e GOVMAP_REQUESTS_PER_SECOND=3.0 \
  nadlan-mcp

Test the Deployment:

# Check health endpoint
curl http://localhost:8000/health

# Expected response:
# {"status":"ok","service":"nadlan-mcp"}

Push to Docker Registry (Optional):

# Tag for Docker Hub
docker tag nadlan-mcp your-username/nadlan-mcp:latest

# Push to Docker Hub
docker push your-username/nadlan-mcp:latest

# Or use GitHub Container Registry
docker tag nadlan-mcp ghcr.io/your-username/nadlan-mcp:latest
docker push ghcr.io/your-username/nadlan-mcp:latest

4.3: Railway Deployment

Step 1: Install Railway CLI (optional) or use web dashboard

npm install -g @railway/cli
railway login

Step 2: Deploy from CLI:

railway init
railway up

Or via Web Dashboard:

• Go to https://railway.app
• Click "New Project" → "Deploy from GitHub repo"
• Select your repository
• Railway auto-detects Dockerfile and deploys

Step 3: Configure Environment Variables

In Railway dashboard, add variables as needed (see Configuration section below)

Step 4: Access Your Service

• Railway provides a public URL
• MCP endpoint: https://your-service.railway.app/mcp
• Health check: https://your-service.railway.app/health

4.4: Other Cloud Platforms

The HTTP server can be deployed to any platform that supports:

• Docker containers
• Python applications
• Port binding via PORT environment variable

Supported Platforms:

• Google Cloud Run - Serverless container deployment
• AWS ECS/Fargate - Container orchestration
• Azure Container Instances - Container deployment
• DigitalOcean App Platform - PaaS deployment
• Heroku - Dyno-based deployment

Deployment Pattern:

1. Use the provided Dockerfile
2. Set PORT environment variable (if not auto-set by platform)
3. Configure health check to GET /health
4. Deploy and access at https://your-domain.com/mcp

Configuration

Environment Variables

Create .env file (optional):

# API Settings
GOVMAP_BASE_URL=https://www.govmap.gov.il/api/
GOVMAP_USER_AGENT=NadlanMCP/2.0.0

# Timeouts (seconds)
GOVMAP_CONNECT_TIMEOUT=10
GOVMAP_READ_TIMEOUT=30

# Retry Settings
GOVMAP_MAX_RETRIES=3
GOVMAP_RETRY_MIN_WAIT=1
GOVMAP_RETRY_MAX_WAIT=10

# Rate Limiting
GOVMAP_REQUESTS_PER_SECOND=5.0

# Performance
GOVMAP_MAX_POLYGONS=10

Programmatic Configuration

from nadlan_mcp.config import GovmapConfig, set_config

config = GovmapConfig(
    connect_timeout=15,
    read_timeout=45,
    max_retries=5,
    requests_per_second=3.0
)
set_config(config)

Verification

Test MCP Tools

In Claude Desktop or your MCP client, try:

Find recent real estate deals for רוטשילד 1 תל אביב

Or use the test script:

python -m pytest tests/e2e/test_mcp_tools.py -v

Check Logs

Enable debug logging:

import logging
logging.basicConfig(level=logging.DEBUG)

Troubleshooting

Server Won't Start

Problem: ImportError or ModuleNotFoundError

Solution:

# Ensure all dependencies installed
pip install -r requirements.txt

# Verify Python version
python --version  # Should be 3.10+

Claude Desktop Not Finding Server

Problem: Server doesn't appear in Claude Desktop

Solution:

1. Check config file path is correct for your OS
2. Use absolute paths in configuration
3. Restart Claude Desktop after config changes
4. Check Claude Desktop logs for errors

API Errors

Problem: requests.exceptions.ConnectionError

Solution:

• Check internet connection
• Verify Govmap API is accessible: curl https://www.govmap.gov.il/api/
• Check firewall/proxy settings

Problem: 429 Too Many Requests

Solution:

• Reduce GOVMAP_REQUESTS_PER_SECOND (default: 5)
• Add delays between requests

No Results Found

Problem: No deals found for this address

Solution:

• Use Hebrew address format: "רוטשילד 1 תל אביב"
• Increase search radius (default: 50m)
• Extend time period: years_back=5

Performance Optimization

For Production Use

1. Increase timeouts for slow networks:

   GOVMAP_READ_TIMEOUT=60
   

2. Adjust rate limiting based on your needs:

   GOVMAP_REQUESTS_PER_SECOND=3.0  # More conservative
   

3. Limit polygon queries to improve speed:

   GOVMAP_MAX_POLYGONS=5  # Fewer API calls
   

Monitoring

import logging

# Enable info logging
logging.basicConfig(
    level=logging.INFO,
    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
)

Updates

Updating Nadlan-MCP

cd nadlan-mcp
git pull
source venv/bin/activate
pip install -r requirements.txt --upgrade

Restart your MCP client to load the updated server.

Security Considerations

1. No API Keys Required: Govmap API is public, no authentication needed
2. Rate Limiting: Built-in to respect API limits
3. Input Validation: All user inputs are validated before API calls
4. No Data Storage: No user data is stored or cached

Support

• Issues: Create issue at repository
• Documentation: See README.md, ARCHITECTURE.md
• Examples: See examples/ directory

---

Note: Nadlan-MCP uses the public Israeli government Govmap API. Please respect rate limits and terms of service.