Berlin Services MCP Server

🚀 Berlin Services MCP Server - Enhanced

This is a production - grade Model Context Protocol (MCP) server designed for Berlin city services (Dienstleistungen). It comes with resilient caching, advanced search, PDF form discovery, and filling capabilities.

✨ Features

• Comprehensive Tools: Search, browse, and obtain detailed information about Berlin services.
• Form Management: Discover, analyze, and fill PDF forms for various services.
• Resilient Caching: Optimized for performance, with intelligent fallback for offline use.
• Remote Sync: Supports both local and remote (Cloud) deployments.

🔧 Technical Details

1. Data Sourcing

The server fetches data from the official Berlin City Services API

• Live Fetching: Tools such as search_services and get_service_details access the live API.
• Resilient Caching: Implements a dual - layer cache (Memory + Disk) to ensure high performance and offline reliability.
• Smart Fallback: If the API is down and there is no cache, it falls back to a minimal set of core services to stay functional.

2. Advanced PDF Processing

Powered by PyMuPDF (fitz), the server offers sophisticated document handling:

• Field Extraction: Automatically detects fillable fields in PDF forms hosted on the city's servers.
• Intelligent Filling: Maps user data to PDF fields using smart matching and common translation fragments.
• Loop Protection: Includes a LoopProtector to prevent redundant tool executions and LLM loops.
• Visual Previews: Can render specific pages of a PDF to JPEG for a quick in - chat snapshot (useful for verification without leaving the chat).

3. Deployment Modes

• Local Mode: Optimized for use with Claude Desktop. In this mode, open_file_locally can be used to open filled PDFs directly with the system's default viewer.
• Remote/Cloud Mode: Designed for deployment on platforms like Fly.io or Railway. Replaces local file opening with secure synchronization and in - chat previews.

📦 Installation

Prerequisites

• Python 3.11 or higher
• uv (recommended) or pip

Local Setup

Using uv (Recommended)

1. Install dependencies and sync the environment:

   uv sync
   

2. Run the server as a module:

   export PYTHONPATH=$PYTHONPATH:$(pwd)/src && uv run python -m berlin_mcp.main
   

   Note: If you've installed the package via uv sync, you can also just run:

   uv run berlin - mcp
   

Using pip

1. Install dependencies:

   pip install -r requirements.txt
   

2. Run the server:

   export PYTHONPATH=$PYTHONPATH:$(pwd)/src && python -m berlin_mcp.main
   

💻 Usage Examples

Claude Desktop Configuration

Add the following to your Claude Desktop configuration file. Replace /Users/mananshah/Desktop/Berlin - Services - MCP - Server with the actual absolute path to the folder.

macOS

File location: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "berlin - services": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/Users/YourUser/Desktop/Berlin - Services - MCP - Server",
        "python",
        "-m",
        "berlin_mcp.main"
      ],
      "env": {
        "PYTHONPATH": "src"
      }
    }
  }
}

Windows

File location: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "berlin - services": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "C:\\Users\\YourUser\\Desktop\\Berlin - Services - MCP - Server",
        "python",
        "-m",
        "berlin_mcp.main"
      ],
      "env": {
        "PYTHONPATH": "src"
      }
    }
  }
}

📚 Documentation

Tools and Resources

The server exposes the following tools to help you navigate and manage Berlin city services:

📄 License

Security Note

⚠️ Important Note

PDF forms filled on remote servers should be downloaded and then deleted using the delete_filled_form tool to ensure data privacy.