MCP Toolbox for Databases - Hybrid SQL & Graph Starter Kit

This repository provides a ready-to-use local environment for the Official MCP Toolbox for Databases by Google. It demonstrates how to bridge relational data (PostgreSQL) and graph data (Neo4j) using the Model Context Protocol (MCP).

✨ What is MCP Toolbox?

MCP Toolbox for Databases is an open-source server from Google that acts as a secure, standardized bridge between AI agents and your data sources.

Key Advantages:

• Abstraction: Agents don't need to handle complex JDBC/Bolt connection strings or raw authentication. They discover and use high-level "tools."
• Hybrid Data Access: Seamlessly combine SQL (Relational) and Cypher (Graph) queries in a single agent session.
• MCP Protocol: Fully compliant with the Model Context Protocol, making it compatible with Claude Desktop, IDEs, and other agentic platforms.
• Security & Control: Centralized configuration of allowed queries (tools) through tools.yaml, preventing unauthorized direct database access.

---

📦 Components Included

1. Google MCP Toolbox Server: The official orchestrator container.
2. PostgreSQL (Relational): Stores structured data (Artists and Albums).
3. Neo4j (Graph): Stores relationships and unstructured metadata (User listening history and Album reviews).
4. Automated Seeding: A dedicated container links data across both databases (e.g., matching a Neo4j Album node to its PostgreSQL ID) to ensure data coherence.

---

🛠️ Getting Started

Prerequisites

• Docker Desktop installed and running.
• Python 3.10+ (if you want to run the test script locally).

1. Environment Setup

Copy the example environment file to the server directory:

# From the root of the project
cp .env server/.env

The .env file contains default credentials such as POSTGRES_USER and NEO4J_PASSWORD.

2. Launch Services

Start the stack using Docker Compose:

cd server
docker compose up -d

This will automatically:

1. Initialize Postgres with the Chinook schema.
2. Initialize Neo4j with the APOC plugin.
3. Run the Seeder to populate Graph data linked to your SQL IDs.
4. Start Toolbox bound to 0.0.0.0:5000 with the tools defined in tools.yaml.

3. Verify Connectivity

Check the Toolbox logs to ensure the server is ready:

docker compose logs toolbox

You should see: INFO "Server ready to serve!".

---

🧪 Testing the Tools

You can use the provided test_toolbox.py script to verify that both databases are correctly serving data through the Toolbox.

1. Install the client library:

   pip install toolbox-core

2. Run the test script:

   python test_toolbox.py

Included Tools:

• search_artists (SQL): Searches for artists in Postgres by name (using $1 positional params).
• get_album_reviews (Cypher): Retrieves graph-based reviews for a specific album ID.
• find_user_listening_history (Cypher): Finds which albums a user has listened to in the graph.

---

🏗️ Project Structure

• /server: Contains docker-compose.yml and the core tools.yaml configuration.
• /init-scripts: Setup scripts for Postgres (init.sql) and Neo4j (seed_neo4j.py).
• test_toolbox.py: A Python client demonstration using toolbox-core.

📚 Resources

• Official Google Database Toolbox Documentation
• Model Context Protocol Specification