semantic-d1

Semantic D1 MCP exposes four MCP tools for Cloudflare D1 database introspection and optimization. These tools—analyze_database_schema, get_table_relationships, validate_database_schema, and suggest_database_optimizations—allow you to understand schema structure, detect foreign key relationships, validate schema health, and receive optimization recommendations. In Claude Desktop or an integrated client, you can invoke these tools with structured JSON payloads to request environment-specific analyses (development, staging, production) and receive detailed results that include schema metadata, relationships, validation findings, and prioritized optimization opportunities. The server emphasizes semantic anchoring and observable properties to preserve intent during development cycles and across environments.

Prerequisites:

• Node.js 20.x or higher
• npm (comes with Node.js)
• Access to a Cloudflare account with a D1 database

Installation steps:

1. Clone the repository: git clone https://github.com/semanticintent/semantic-d1-mcp.git cd semantic-d1-mcp

2. Install dependencies: npm install

3. Build the server (produces dist/index.js): npm run build

4. Prepare environment variables:

   • Copy the example env file if provided, or create a .env file with required keys (see mcp_config.env below).
   • Ensure CLOUDFLARE_ACCOUNT_ID, CLOUDFLARE_API_TOKEN, D1_DEV_DATABASE_ID/NAME, D1_STAGING_DATABASE_ID/NAME, D1_PROD_DATABASE_ID/NAME are set as appropriate for your setup.

5. Run the MCP server: npm start

Alternative (if available): ./start-d1-mcp.sh

Notes:

• The dist/index.js path in mcp_config should reflect your actual build output location.
• Ensure network access to Cloudflare APIs and D1 databases from the host running the MCP server.

Tips and common issues:

• Ensure your Cloudflare API token has at least D1:Read permissions when using D1-related tools.
• At least one D1 environment (development, staging, or production) must be configured in the .env/.env-like configuration.
• When using Claude Desktop integration, update the absolute path in the mcpServers configuration to point to your built dist/index.js file.
• If you encounter connection errors, verify that the env variables are correctly loaded by the runtime and that network egress to Cloudflare endpoints is allowed.
• Tools operate per environment; results may vary across development, staging, and production due to schema differences.