Datastore Server

A Model Context Protocol (MCP) server that provides access to Google Cloud Datastore. This server enables AI assistants like Claude to interact with Datastore entities, perform queries, and manage data.

Features

• Entity Operations: Create, read, update, and delete Datastore entities
• Query Support: Execute queries with filters, ordering, and pagination
• Namespace Support: Work with different Datastore namespaces
• Emulator Support: Connect to local Datastore emulator by default for development
• Production Ready: Easy configuration for production Google Cloud Datastore

Installation

Prerequisites

Option 1: Docker (Recommended)

• Docker Engine 20.10+
• Docker Compose v2.0+

Option 2: Local Python

• Python 3.10 or higher
• Google Cloud Datastore emulator (for local development) or Google Cloud project (for production)

Install from source

# Clone the repository
git clone <repository-url>
cd datastore-mcp

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -e .

Using uv (recommended)

# Create virtual environment and install dependencies
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv pip install -e .

Using Docker (recommended for testing)

Docker provides an isolated environment with both the Datastore emulator and MCP server pre-configured.

# Run tests
make test

# Start all services (emulator + server)
make up

# View logs
make logs

# Stop services
make down

For detailed Docker documentation, see DOCKER.md.

Configuration

The server can be configured using environment variables or command-line arguments.

Environment Variables

For Emulator:

• DATASTORE_DATASET - Dataset name (default: test)
• DATASTORE_EMULATOR_HOST - Datastore emulator host (default: localhost:8081)
• DATASTORE_EMULATOR_HOST_PATH - Emulator host path (default: localhost:8081/datastore)
• DATASTORE_HOST - Datastore HTTP host (default: http://localhost:8081)
• DATASTORE_PROJECT_ID - Google Cloud project ID (default: test)
• DATASTORE_NAMESPACE - Default namespace (optional)

For Production:

• DATASTORE_PROJECT_ID - Google Cloud project ID (required)
• GOOGLE_APPLICATION_CREDENTIALS - Path to service account key file (required)
• DATASTORE_NAMESPACE - Default namespace (optional)

Running with Datastore Emulator (Default)

# Start the Datastore emulator (in a separate terminal)
gcloud beta emulators datastore start --host-port=localhost:8081

# Run the MCP server (uses emulator by default)
python src/datastore_mcp/server.py

# Or with custom emulator host
DATASTORE_EMULATOR_HOST=localhost:9090 python src/datastore_mcp/server.py

Running with Production Datastore

# Set credentials and project
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account-key.json
export DATASTORE_PROJECT_ID=your-gcp-project-id

# Unset emulator host to use production
unset DATASTORE_EMULATOR_HOST

# Run the server
python src/datastore_mcp/server.py

Usage with Claude Desktop

Add this configuration to your Claude Desktop config file:

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

For Emulator (Development)

{
  "mcpServers": {
    "datastore": {
      "command": "python",
      "args": ["/path/to/datastore-mcp/src/datastore_mcp/server.py"],
      "env": {
        "DATASTORE_DATASET": "test",
        "DATASTORE_EMULATOR_HOST": "localhost:8081",
        "DATASTORE_EMULATOR_HOST_PATH": "localhost:8081/datastore",
        "DATASTORE_HOST": "http://localhost:8081",
        "DATASTORE_PROJECT_ID": "test"
      }
    }
  }
}

For Production

{
  "mcpServers": {
    "datastore": {
      "command": "python",
      "args": ["/path/to/datastore-mcp/src/datastore_mcp/server.py"],
      "env": {
        "DATASTORE_PROJECT_ID": "your-gcp-project-id",
        "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/service-account-key.json"
      }
    }
  }
}

Using Docker with Claude Desktop (Recommended)

Option 1: Fully Automated (Emulator + Server)

Use the provided wrapper script (included in the repository):

MacOS/Linux: start-datastore-mcp.sh Windows: start-datastore-mcp.bat

Then configure Claude Desktop:

MacOS/Linux:

{
  "mcpServers": {
    "datastore": {
      "command": "/path/to/datastore-mcp/start-datastore-mcp.sh"
    }
  }
}

Windows:

{
  "mcpServers": {
    "datastore": {
      "command": "C:\\path\\to\\datastore-mcp\\start-datastore-mcp.bat"
    }
  }
}

This option automatically starts the emulator if it's not running and waits for it to be healthy before starting the MCP server.

Option 2: Manual Emulator Start

First, start the Datastore emulator once:

cd /path/to/datastore-mcp
make emulator-only  # Keeps running in background

Then configure Claude Desktop:

{
  "mcpServers": {
    "datastore": {
      "command": "docker",
      "args": [
        "compose",
        "-f",
        "/path/to/datastore-mcp/docker-compose.yml",
        "run",
        "--rm",
        "mcp-server"
      ]
    }
  }
}

Option 3: External Emulator (Custom IP)

If your emulator runs on a different machine or custom IP:

{
  "mcpServers": {
    "datastore": {
      "command": "docker",
      "args": [
        "compose",
        "-f",
        "/path/to/datastore-mcp/docker-compose.yml",
        "run",
        "--rm",
        "-e", "DATASTORE_EMULATOR_HOST=localhost:8081",
        "-e", "DATASTORE_EMULATOR_HOST_PATH=localhost:8081/datastore",
        "-e", "DATASTORE_HOST=http://localhost:8081",
        "mcp-server"
      ]
    }
  }
}

Using uv with Claude Desktop

{
  "mcpServers": {
    "datastore": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/datastore-mcp",
        "run",
        "datastore-mcp"
      ],
      "env": {
        "DATASTORE_DATASET": "test",
        "DATASTORE_EMULATOR_HOST": "localhost:8081",
        "DATASTORE_EMULATOR_HOST_PATH": "localhost:8081/datastore",
        "DATASTORE_HOST": "http://localhost:8081",
        "DATASTORE_PROJECT_ID": "test"
      }
    }
  }
}

Available Tools

Once connected, the following tools are available to Claude:

• datastore_get - Retrieve an entity by key
• datastore_put - Create or update an entity
• datastore_delete - Delete an entity
• datastore_query - Query entities with filters and ordering
• datastore_batch_get - Retrieve multiple entities by keys
• datastore_list_kinds - List all entity kinds in the namespace

Example Queries

Ask Claude to:

• "Get the User entity with ID 12345"
• "Query all Products where price > 100, ordered by name"
• "Create a new BlogPost entity with title and content"
• "Delete the Comment entity with ID abc123"
• "List all entity kinds in my datastore"

Development

Using Docker (Recommended)

# Run tests
make test

# Run tests with coverage
docker-compose run --rm test

# Start emulator only for local development
make emulator-only

# Interactive shell in container
make shell

Using Local Python

# Install development dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run tests with coverage
pytest --cov=src/datastore_mcp --cov-report=term-missing

# Run the server
python src/datastore_mcp/server.py

Project Structure

datastore-mcp/
├── src/
│   └── datastore_mcp/
│       ├── server.py          # Main MCP server
│       ├── datastore.py       # Datastore client wrapper
│       └── tools.py           # Tool implementations
├── tests/
│   └── test_tools.py
├── pyproject.toml
└── README.md

License

MIT License

Contributing

Contributions are welcome! Please open an issue or submit a pull request.