Prisma MCP Server

This package provides a Model Context Protocol (MCP) server that acts as an interface to a database managed by Prisma ORM. It allows MCP-compatible clients (like AI assistants or other applications) to interact with your database by querying resources and executing tools.

This server uses fastmcp to expose Prisma models and operations.

Features

Resource Loading: Exposes Prisma models as readable MCP resources (e.g., resource://users/{user_id}, resource://projects).
Tool Execution: Provides MCP tools for common CRUD (Create, Read, Update, Delete) operations on your Prisma models (e.g., create_user, update_project).
Database Interaction: Handles the translation between MCP requests and Prisma Client database queries.
Configurable Transport: Supports both stdio and sse (Server-Sent Events over HTTP) transport modes.
Extensible: Easily add custom resources or tools for more complex operations or interactions with other application services.

Prerequisites

Node.js: A recent version (check package.json engines if specified).
Yarn or npm: Package manager.
Prisma Client: Your consuming project must have @prisma/client installed and a prisma/schema.prisma file configured for your target database.
Database: A running database instance supported by Prisma (e.g., PostgreSQL, MySQL, SQLite).

Installation

# Using yarn
yarn add cadcamfun-db-mcp-server @prisma/client

# Using npm
npm install cadcamfun-db-mcp-server @prisma/client

Note: You must install @prisma/client as a peer dependency in the project using this server package.

Setup in Consuming Project

Prisma Schema: Ensure you have a valid prisma/schema.prisma file in your project root defining your database connection and models.
Environment Variables: Configure the necessary environment variables (e.g., in a .env file). Do not commit sensitive variables like DATABASE_URL directly to version control.
- DATABASE_URL: (Required) The connection string for your database (e.g., postgresql://user:password@host:port/database).
- TRANSPORT_TYPE: (Optional) Set to sse to use Server-Sent Events over HTTP. Defaults to stdio.
- PORT: (Optional, requires TRANSPORT_TYPE=sse) Port for the SSE server. Defaults to 8080.
- MAIN_APP_URL: (Optional) Base URL for your main application if using tools that need to call back to it (e.g., trigger_main_app_notification). Defaults to http://localhost:3000.
- LOG_LEVEL: (Optional) Controls logging verbosity. Set to DEBUG, INFO, WARN, or ERROR. Behavior depends on the logger implementation within the package (if used).
Generate Prisma Client: Before running the server, you must generate the Prisma Client based on your schema:
```
npx prisma generate
```
This step is crucial as the server relies on the generated client in node_modules/@prisma/client.

Usage

// Example: index.ts in your consuming project

// Import the server creation function
import { createPrismaMcpServer } from 'prisma-mcp-server';
import { PrismaClient } from '@prisma/client'; // Make sure Prisma Client is installed

// Ensure required environment variables are set
if (!process.env.DATABASE_URL) {
  console.error("Error: DATABASE_URL environment variable is not set.");
  process.exit(1);
}

// Optional: Configure transport type and port via environment variables
// process.env.TRANSPORT_TYPE = 'sse';
// process.env.PORT = '8081';

async function main() {
  // Ensure Prisma Client is generated (Best done in a build step)
  try {
    // Check if client exists, generate if not (simple check)
    require.resolve('@prisma/client'); 
  } catch (e) {
      console.log('Prisma Client not found, attempting to generate...');
      try {
          const { execSync } = require('child_process');
          execSync('npx prisma generate', { stdio: 'inherit' });
          console.log('Prisma Client generated.');
      } catch (error) {
          console.error('Error generating Prisma Client:', error);
          process.exit(1);
      }
  }

  // Create the server instance
  const server = createPrismaMcpServer({
    // Optional: Override default server info if needed
    // name: "MyCustomServerName",
    // version: "2.0.0",
    // instructions: "Custom instructions..."
  });

  console.log(`Starting Prisma MCP Server...`);

  // Determine transport options based on environment variables
  const transportType = process.env.TRANSPORT_TYPE === 'sse' ? 'sse' : 'stdio';
  const port = parseInt(process.env.PORT || "8080");
  const sseEndpoint = "/sse"; // Assuming hardcoded endpoint

  const startOptions: any = { transportType }; // Use 'any' temporarily if exact type is complex
  if (transportType === 'sse') {
    startOptions.sse = { endpoint: sseEndpoint, port: port };
  }

  // Start the server using the options derived from environment variables
  server.start(startOptions);

  console.log(`Server started with transport: ${transportType}`);
  if (transportType === 'sse') {
      console.log(`SSE endpoint available at http://localhost:${port}${sseEndpoint}`);
  }
}

main().catch((e) => {
  console.error(e);
  process.exit(1);
});

Now you can connect your MCP client to the running server using the configured transport method (stdio or the /sse endpoint).

Connecting with Claude Desktop

Claude Desktop (or similar MCP clients) can connect to this server using either the stdio or sse transport method.

Configure Transport:
- Before starting the server, set the TRANSPORT_TYPE environment variable in your consuming project's environment (e.g., in your .env file or system environment):
  - TRANSPORT_TYPE=stdio (Default): The server will communicate over standard input and output.
  - TRANSPORT_TYPE=sse: The server will start an HTTP server for Server-Sent Events.
- If using sse, you can also set the PORT environment variable (defaults to 8080).
Start the Server:
- Run your consuming application's entry point (e.g., node your-app-entrypoint.js) which includes the code to create and start the prisma-mcp-server (as shown in the Usage section).
Connect Claude Desktop:
- If using stdio: Configure Claude Desktop to launch the server process directly. This usually involves providing the command to start your application (e.g., node /path/to/your-app-entrypoint.js or yarn start if you have a start script).
- If using sse: Configure Claude Desktop to connect to the HTTP endpoint. The default URL will be http://localhost:8080/sse. If you changed the PORT, adjust accordingly.
Identify the Server:
- In Claude Desktop, you might need to identify the server. By default, it's named PrismaAPI_Server (version 1.1.0), but this can be overridden when calling createPrismaMcpServer.

Example mcp.json Snippets for Claude Desktop:

Using stdio:

{
  "mcpServers": {
    "prisma_api_stdio": {
      "name": "Prisma API Server (stdio)", // Optional display name
      // Option 1: Using npx with a script/package name
      "command": "npx",
      "args": [
        "cadcamfun-db-mcp-server" // Replace with your actual script/package name
      ],
      // Option 2: Using yarn/npm run script
      // "command": "yarn", 
      // "args": ["start:prisma-mcp"], // Assuming a script named 'start:prisma-mcp'
      "workingDirectory": "" // Replace with the path to your CONSUMING project root
    }
  }
}

Using sse:

{
  "mcpServers": {
    "prisma_api_sse": {
      "name": "Prisma API Server (SSE)", // Optional display name
      // Assumes the server is running and listening on port 8080 (default)
      // The port can be changed via the PORT environment variable when starting the server.
      "url": "http://localhost:8080/sse" 
    }
  }
}

Refer to your specific MCP client's documentation for the exact steps on how to add and configure a new MCP server connection.

Available Resources & Tools

This server exposes MCP resources and tools corresponding to the Prisma models defined in its internal schema (prisma/schema.prisma within the package, although it uses the consuming project's generated client).

Resources (Examples):

resource://users
resource://users/{user_id}
resource://projects
resource://projects/{project_id}
resource://drawings?project_id={project_id}
resource://drawings/{drawing_id}
resource://components?project_id={project_id}
resource://components/{component_id}
resource://materials
resource://materials/{material_id}
resource://tools
resource://tools/{tool_id}
resource://machine-configs
resource://machine-configs/{machine_config_id}
resource://toolpaths?project_id={project_id}
resource://toolpaths/{toolpath_id}
resource://library-items
resource://library-items/{library_item_id}

(Refer to src/resources.ts for the complete list and arguments)

Tools (Examples):

create_user, update_user, delete_user
create_subscription, update_subscription, delete_subscription
create_organization, update_organization, delete_organization
create_project, update_project, delete_project
create_drawing, update_drawing, delete_drawing
create_component, update_component, delete_component
create_material, update_material, delete_material
create_tool_prisma, update_tool_prisma, delete_tool_prisma
create_machine_config, update_machine_config, delete_machine_config
create_toolpath, update_toolpath, delete_toolpath
create_library_item, update_library_item, delete_library_item
trigger_main_app_notification (Example custom tool)

(Refer to src/tools.ts for the complete list and parameters defined using Zod)

Extending

You can fork this package or use it as a base to add your own custom resources and tools by modifying src/resources.ts and src/tools.ts. Remember to rebuild (yarn build) after making changes.

Deployment

Configure Database: Ensure your production DATABASE_URL environment variable is set correctly in your deployment environment (e.g., server environment variables, secrets manager). Do not commit this to your repository.
Environment Variables: Set TRANSPORT_TYPE (sse or stdio) and optionally PORT and MAIN_APP_URL in your deployment environment.

Build & Run:

# Navigate to your project directory (where prisma-mcp-server is a dependency)

# Install dependencies
yarn install --production # Or npm install --omit=dev

# Generate Prisma Client (Important! Needs DATABASE_URL)
npx prisma generate

# Apply Migrations (Needs DATABASE_URL - Replace with your strategy)
# Example:
# npx prisma migrate deploy 

# Build your application (which includes the server code)
yarn build # Or your specific build command

# Start your application (which starts the MCP server)
# Use a process manager like pm2 in production
# Example:
# pm2 start your-app-entrypoint.js 
# OR
# node your-app-entrypoint.js

License

[MIT]