Berlin Services MCP Server is a feature-rich Python-based MCP server that provides structured access to Berlin city services. It exposes tools for searching, browsing, and retrieving detailed information about services, as well as discovering and filling PDF forms related to those services. The server implements resilient caching and supports both local and remote (cloud) deployments, with specialized capabilities for PDF form handling via PyMuPDF. To use it locally, start the server with the provided command and then invoke the available tools through the MCP interface to perform tasks like searching for services, obtaining service details, and managing forms. The tooling includes options for field extraction, filling, preview rendering, and secure synchronization when running in remote mode.

Prerequisites:

• Python 3.11 or higher
• Git (optional, for cloning the repository)
• Internet access to install dependencies

Step-by-step installation:

1. Clone or download the repository containing the Berlin-Services MCP Server.
2. Create a Python virtual environment (optional but recommended): python -m venv venv

   On Windows: venv\Scripts\activate

   On macOS/Linux: source venv/bin/activate

3. Install required Python packages: pip install -r requirements.txt
4. Ensure the Python path includes the source code when running the server: export PYTHONPATH=$PYTHONPATH:$(pwd)/src
5. Start the MCP server: python -m berlin_mcp.main
6. (Optional) If you plan to run via Claude Desktop, ensure your environment variables and paths match your OS-specific guidance (see Claude Desktop configuration in the README).

Notes:

• If you prefer an alternative local workflow, you can use uv (uvx) to run the server as a module or via the package entry points, but the recommended approach in this repository uses python -m berlin_mcp.main with PYTHONPATH adjusted to src.

Tips and common considerations:

• The server uses a dual-layer cache (memory + disk) to optimize performance and support offline operation. Ensure sufficient disk space for caching data.
• For remote/cloud deployments, the system replaces local file opening with secure synchronization and in-chat previews; configure environment variables if needed for your hosting platform.
• PDF form handling relies on PyMuPDF (fitz). Ensure PyMuPDF is installed and compatible with your Python version.
• Tools exposed include search_services, get_service_details, get_service_forms, analyze_form_for_filling, perform_form_filling, download_filled_form, get_form_visual_preview, and many more. Use the commands provided by your MCP client to invoke these tools.
• For Claude Desktop users, the configuration example in the README demonstrates wiring the command and environment for local execution. If you switch to a remote deployment, adapt the directory paths accordingly and ensure PYTHONPATH is set to the src directory.
• If the API source ever goes offline, the server will attempt to serve a minimal core set of services from cache; without any cache that fallback may be limited, so consider ensuring cache priming in advance for critical workflows.