📌Overview

Purpose: To provide a standardized interface for LLM applications to interact seamlessly with the Nile database platform.

Overview: The Nile MCP Server is a Model Context Protocol (MCP) server implementation designed for the Nile database platform. It facilitates efficient communication between applications and databases, enabling developers to manage databases and execute SQL queries effectively through a well-structured interface.

Key Features:

• Database Management: Allows users to create, list, get details, and delete databases efficiently.

• Credential Management: Simplifies the creation and listing of database credentials needed for secure operations.

• Region Management: Provides users with the ability to list available regions for database creation, enhancing deployment options.

• SQL Query Support: Enables direct execution of SQL queries on Nile databases, streamlining data manipulation.

• MCP Protocol Support: Fully implements the Model Context Protocol for robust and flexible database interactions.

• Type Safety: Built with TypeScript, ensuring full type checking for improved code reliability.

• Error Handling: Incorporates comprehensive error handling with user-friendly error messages for a better developer experience.

• Test Coverage: Includes a comprehensive test suite utilizing Jest, ensuring the reliability and functionality of the server.

• Environment Management: Automatically loads environment variables from a .env file for simplified configuration.

• Input Validation: Features schema-based input validation using Zod, enhancing data integrity during operations.

---

Nile MCP Server

A Model Context Protocol (MCP) server implementation for the Nile database platform. This server allows LLM applications to interact with the Nile platform through a standardized interface.

Features

• Database Management: Create, list, get details, and delete databases
• Credential Management: Create and list database credentials
• Region Management: List available regions for database creation
• SQL Query Support: Execute SQL queries directly on Nile databases
• MCP Protocol Support: Full implementation of the Model Context Protocol
• Type Safety: Written in TypeScript with full type checking
• Error Handling: Comprehensive error handling and user-friendly error messages
• Test Coverage: Comprehensive test suite using Jest
• Environment Management: Automatic loading of environment variables from .env file
• Input Validation: Schema-based input validation using Zod

Installation

Install the stable version:

npm install @niledatabase/nile-mcp-server

For the latest alpha/preview version:

npm install @niledatabase/nile-mcp-server@alpha

Manual Installation

# Clone the repository
git clone https://github.com/yourusername/nile-mcp-server.git
cd nile-mcp-server

# Install dependencies
npm install

# Build the project
npm run build

Other MCP Package Managers

npx @michaellatman/mcp-get@latest install @niledatabase/nile-mcp-server

Starting the Server

Several ways to start the server:

1. Direct Node Execution:

   node dist/index.js
   

2. Development Mode (with auto-rebuild):

   npm run dev
   

The server will start and listen for MCP protocol messages. To stop the server, press Ctrl+C.

Verifying the Server is Running

When started successfully, logs indicate:

[info] Starting Nile MCP Server...
[info] Loading environment variables...
[info] Environment variables loaded successfully
[info] Creating server instance...
[info] Tools initialized successfully
[info] Setting up stdio transport...
[info] Server started successfully

Configuration

Create a .env file in the root directory with your Nile credentials:

NILE_API_KEY=your_api_key_here
NILE_WORKSPACE_SLUG=your_workspace_slug

To create a Nile API key, log in to your Nile account, navigate to your workspace, and generate a key in the Security section.

Using with Claude Desktop

Setup

1. Install Claude Desktop if you haven't already.
2. Build the project:

   npm run build
   

3. Open Claude Desktop.
4. Go to Settings > MCP Servers.
5. Click "Add Server" and add the following configuration:

{
  "mcpServers": {
    "nile-database": {
      "command": "node",
      "args": [
        "/path/to/your/nile-mcp-server/dist/index.js"
      ],
      "env": {
        "NILE_API_KEY": "your_api_key_here",
        "NILE_WORKSPACE_SLUG": "your_workspace_slug"
      }
    }
  }
}

Replace:

• /path/to/your/nile-mcp-server with the absolute path to your project directory
• your_api_key_here with your Nile API key
• your_workspace_slug with your Nile workspace slug

Using with Cursor

Setup

1. Install Cursor if you haven't already.
2. Build the project:

   npm run build
   

3. Open Cursor.
4. Go to Settings (⌘,) > Features > MCP Servers.
5. Click "Add New MCP Server".
6. Configure the server:
   • Name: nile-database (or any name you prefer)
   • Command:

     env NILE_API_KEY=your_key NILE_WORKSPACE_SLUG=your_workspace node /absolute/path/to/nile-mcp-server/dist/index.js
     

   Replace placeholders accordingly.
7. Click "Save".
8. Restart Cursor to apply changes.

Server Modes

The server supports two operational modes:

STDIO Mode (Default)

Uses standard input/output for communication; compatible with Claude Desktop and Cursor.

SSE Mode

Enables real-time event-driven communication over HTTP.

To enable SSE mode:

1. Set MCP_SERVER_MODE=sse in your .env file.
2. The server starts an HTTP server (default port 3000).
3. Connect to SSE endpoint: http://localhost:3000/sse
4. Send commands to: http://localhost:3000/messages

Example SSE usage with curl:

# Terminal 1 - Listen for events
curl -N http://localhost:3000/sse

# Terminal 2 - Send commands
curl -X POST http://localhost:3000/messages \
  -H "Content-Type: application/json" \
  -d '{
    "type": "function",
    "name": "list-databases",
    "parameters": {}
  }'

Example Prompts

Use natural language to interact with Nile databases:

Database Management

Create a new database named "my_app" in AWS_US_WEST_2 region
List all my databases
Get details for database "my_app"
Delete database "test_db"

Creating Tables

Create a users table in my_app database with columns:
- tenant_id (UUID, references tenants)
- id (INTEGER)
- email (VARCHAR, unique per tenant)
- name (VARCHAR)
- created_at (TIMESTAMP)

Querying Data

Execute this query on my_app database:
SELECT * FROM users WHERE tenant_id = 'your-tenant-id' LIMIT 5

Schema Management

Show me the schema for the users table in my_app database
Add a new column 'status' to the users table in my_app database
Create an index on the email column of the users table in my_app

Available Tools

Database Management

• create-database: Create a new Nile database

  • Parameters: name (string), region (string: AWS_US_WEST_2 or AWS_EU_CENTRAL_1)
  • Returns: Database details
  • Example: "Create a database named 'my-app' in AWS_US_WEST_2"

• list-databases: List all databases in your workspace

  • Returns: List of databases with IDs, names, regions, and status
  • Example: "List all my databases"

• get-database: Get detailed info on a specific database

  • Parameters: name (string)
  • Returns: Detailed database info including API and DB hosts
  • Example: "Get details for database 'my-app'"

• delete-database: Delete a database

  • Parameters: name (string)
  • Returns: Confirmation message
  • Example: "Delete database 'my-app'"

Credential Management

• list-credentials: List credentials for a database

  • Parameters: databaseName (string)
  • Returns: List of credentials with IDs, usernames, creation dates
  • Example: "List credentials for database 'my-app'"

• create-credential: Create new credentials for a database

  • Parameters: databaseName (string)
  • Returns: Credential details including username and one-time password
  • Example: "Create new credentials for database 'my-app'"
  • Note: Save password on first display; it will not be shown again.

Region Management

• list-regions: List available regions for database creation
  • Returns: List of AWS regions
  • Example: "What regions are available for creating databases?"

SQL Query Execution

• execute-sql: Execute SQL queries on a Nile database
  • Parameters:
    • databaseName (string)
    • query (string)
    • connectionString (string, optional)
  • Returns: Query results as markdown table
  • Features:
    • Automatic credential management
    • Secure SSL connection
    • Detailed error messages with hints
    • Support for existing connection strings
  • Example: "Execute SELECT * FROM users LIMIT 5 on database 'my-app'"

Resource Management

• read-resource: Read schema for database resources (tables/views)

  • Parameters: databaseName (string), resourceName (string)
  • Returns: Schema info including columns, keys, indexes, relationships
  • Example: "Show me the schema for the users table in my-app"

• list-resources: List all resources in a database

  • Parameters: databaseName (string)
  • Returns: List of tables, views, etc.
  • Example: "List all tables in my-app database"

Tenant Management

• list-tenants: List tenants in a database

  • Parameters: databaseName (string)
  • Returns: List of tenants with IDs and metadata
  • Example: "Show all tenants in my-app database"

• create-tenant: Create a new tenant

  • Parameters: databaseName (string), tenantName (string)
  • Returns: Tenant details including ID
  • Example: "Create a tenant named 'acme-corp' in my-app"

• delete-tenant: Delete tenants

  • Parameters: databaseName (string), tenantName (string)
  • Returns: Success status
  • Example: "Delete tenant named 'acme-corp' in my-app"

Example Usage Commands

# Database Management
Please create a new database named "my-app" in the AWS_US_WEST_2 region.
Can you list all my databases?
Get the details for database "my-app".
Delete the database named "test-db".

# SQL Queries
Execute SELECT * FROM users LIMIT 5 on database "my-app"
Run this query on my-app database: SELECT COUNT(*) FROM orders WHERE status = 'completed'
Using connection string "postgres://user:pass@host:5432/db", execute this query on my-app: SELECT * FROM products WHERE price > 100

Response Format

• Success: includes relevant data and confirmation messages
• Errors: detailed messages with HTTP status codes
• SQL results formatted as markdown tables
• Responses optimized for Claude Desktop readability

Error Handling

Handles various errors including:

• Invalid API credentials
• Network connectivity issues
• Invalid database names or regions
• Missing parameters
• Database operation failures
• SQL syntax errors with hints
• Rate limiting and API restrictions

Troubleshooting

• Check server path in configuration if tools are inaccessible.
• Ensure project is built (npm run build).
• Verify API key and workspace slug.
• Restart Claude Desktop or Cursor after changes.
• Confirm API key permissions and database uniqueness when creating databases.
• Confirm database state and permissions when managing credentials.

Development

Project Structure

nile-mcp-server/
├── src/
│   ├── server.ts      # MCP server implementation
│   ├── tools.ts       # Tool implementations
│   ├── types.ts       # Type definitions
│   ├── logger.ts      # Logging utilities
│   ├── index.ts       # Entry point
│   └── __tests__/     # Test files
│       └── server.test.ts
├── dist/              # Compiled JavaScript
├── logs/              # Log files directory
├── .env               # Environment configuration
├── .gitignore         # Git ignore file
├── package.json       # Project dependencies
└── tsconfig.json      # TypeScript configuration

Key Files

• server.ts: Main server code with tool registration and transport handling
• tools.ts: Database operations and SQL execution logic
• types.ts: TypeScript interfaces for operations and responses
• logger.ts: Structured logging with rotation and debug support
• index.ts: Server startup and environment loading
• server.test.ts: Tests for functionality coverage

Development Commands

# Install dependencies
npm install

# Build the project
npm run build

# Start server in production mode
node dist/index.js

# Start server using npm
npm start

# Start in development mode with auto-rebuild
npm run dev

# Run tests
npm test

NPM Scripts

• build: Compile TypeScript
• start: Run production server
• dev: Development mode with rebuild
• test: Run test suite
• lint: Run ESLint checks
• clean: Remove build files

Testing

Comprehensive tests cover:

• Tool registration and validation
• Database management
• Connection handling
• SQL execution and error handling
• Response formatting

Run with:

npm test

Logging

Features:

• Daily rotating logs
• Separate debug and API logs
• JSON format with timestamps
• Console output during development
• Categories: info, error, debug, api, sql, startup

License

MIT License – See LICENSE for details.

Related Links

• Model Context Protocol
• Nile Database
• Claude Desktop
• Cursor