Nile Database

<a href="https://thenile.dev">Website</a>

<a href="https://github.com/orgs/niledatabase/discussions">Issues</a> </p>

![smithery badge](https://smithery.ai/badge/@niledatabase/nile-mcp-server)

A Model Context Protocol (MCP) server implementation for Nile database platform. This server allows LLM applications to interact with 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:

For the latest alpha/preview version:

This will install @niledatabase/nile-mcp-server in your node_modules folder. For example: node_modules/@niledatabase/nile-mcp-server/dist/

Manual Installation

Starting the Server

There are several ways to start the server:

Direct Node Execution:

Development Mode (with auto-rebuild):

The server will start and listen for MCP protocol messages. You should see startup logs indicating:

Environment variables loaded

Server instance created

Tools initialized

Transport connection established

To stop the server, press Ctrl+C.

Verifying the Server is Running

When the server starts successfully, you should see logs similar to:

If you see these logs, the server is ready to accept commands from Claude Desktop.

Configuration

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

To create a Nile API key, log in to your Nile account, click Workspaces in the top-left, select your workspace, and navigate to the Security section in the left menu.

Using with Claude Desktop

Setup

Install Claude Desktop if you haven't already

Build the project:

Open Claude Desktop

Go to Settings > MCP Servers

Click "Add Server"

Add the following configuration:

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

Install Cursor if you haven't already

Build the project:

Open Cursor

Go to Settings ( ,) > Features > MCP Servers

Click "Add New MCP Server"

Configure the server:

Click "Save"

You should see a green indicator showing that the MCP server is connected

Restart Cursor for the changes to take effect

Server Modes

The server supports two operational modes:

STDIO Mode (Default)

The default mode uses standard input/output for communication, making it compatible with Claude Desktop and Cursor integrations.

SSE Mode

Server-Sent Events (SSE) mode enables real-time, event-driven communication over HTTP.

To enable SSE mode:

Set MCP_SERVER_MODE=sse in your .env file

The server will start an HTTP server (default port 3000)

Connect to the SSE endpoint: http://localhost:3000/sse

Send commands to: http://localhost:3000/messages

Example SSE usage with curl:

Example Prompts

After setting up the MCP server in Cursor, you can use natural language to interact with Nile databases. Here are some example prompts:

Database Management

Creating Tables

Querying Data

Schema Management

Available Tools

The server provides the following tools for interacting with Nile databases:

Database Management

create-database

list-databases

get-database

delete-database

Credential Management

list-credentials

create-credential

Region Management

list-regions

SQL Query Execution

execute-sql

Resource Management

read-resource

list-resources

Tenant Management

list-tenants

create-tenant

delete-tenant

Example Usage

Here are some example commands you can use in Claude Desktop:

Response Format

All tools return responses in a standardized format:

Success responses include relevant data and confirmation messages

Error responses include detailed error messages and HTTP status codes

SQL query results are formatted as markdown tables

All responses are formatted for easy reading in Claude Desktop

Error Handling

The server handles various error scenarios:

Invalid API credentials

Network connectivity issues

Invalid database names or regions

Missing required parameters

Database operation failures

SQL syntax errors with helpful hints

Rate limiting and API restrictions

Troubleshooting

If Claude says it can't access the tools:

If database creation fails:

If credential operations fail:

Development

Project Structure

Key Files

server.ts: Main server implementation with tool registration and transport handling

tools.ts: Implementation of all database operations and SQL query execution

types.ts: TypeScript interfaces for database operations and responses

logger.ts: Structured logging with daily rotation and debug support

index.ts: Server startup and environment configuration

server.test.ts: Comprehensive test suite for all functionality

Development

Development Scripts

The following npm scripts are available:

npm run build: Compiles TypeScript to JavaScript

npm start: Starts the server in production mode

npm run dev: Starts the server in development mode with auto-rebuild

npm test: Runs the test suite

npm run lint: Runs ESLint for code quality checking

npm run clean: Removes build artifacts

Testing

The project includes a comprehensive test suite that covers:

Tool registration and schema validation

Database management operations

Connection string generation

SQL query execution and error handling

Response formatting and error cases

Run the tests with:

Logging

The server uses structured logging with the following features:

Daily rotating log files

Separate debug logs

JSON formatted logs with timestamps

Console output for development

Log categories: info, error, debug, api, sql, startup

License

MIT License - See LICENSE for details.

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:

For the latest alpha/preview version:

This will install @niledatabase/nile-mcp-server in your node_modules folder. For example: node_modules/@niledatabase/nile-mcp-server/dist/

Manual Installation

Starting the Server

There are several ways to start the server:

Direct Node Execution:

Development Mode (with auto-rebuild):

The server will start and listen for MCP protocol messages. You should see startup logs indicating:

Environment variables loaded

Server instance created

Tools initialized

Transport connection established

To stop the server, press Ctrl+C.

Verifying the Server is Running

When the server starts successfully, you should see logs similar to:

If you see these logs, the server is ready to accept commands from Claude Desktop.

Configuration

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

To create a Nile API key, log in to your Nile account, click Workspaces in the top-left, select your workspace, and navigate to the Security section in the left menu.

Using with Claude Desktop

Setup

Install Claude Desktop if you haven't already

Build the project:

Open Claude Desktop

Go to Settings > MCP Servers

Click "Add Server"

Add the following configuration:

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

Install Cursor if you haven't already

Build the project:

Open Cursor

Go to Settings ( ,) > Features > MCP Servers

Click "Add New MCP Server"

Configure the server:

Click "Save"

You should see a green indicator showing that the MCP server is connected

Restart Cursor for the changes to take effect

Server Modes

The server supports two operational modes:

STDIO Mode (Default)

The default mode uses standard input/output for communication, making it compatible with Claude Desktop and Cursor integrations.

SSE Mode

Server-Sent Events (SSE) mode enables real-time, event-driven communication over HTTP.

To enable SSE mode:

Set MCP_SERVER_MODE=sse in your .env file

The server will start an HTTP server (default port 3000)

Connect to the SSE endpoint: http://localhost:3000/sse

Send commands to: http://localhost:3000/messages

Example SSE usage with curl:

Example Prompts

After setting up the MCP server in Cursor, you can use natural language to interact with Nile databases. Here are some example prompts:

Database Management

Creating Tables

Querying Data

Schema Management

Available Tools

The server provides the following tools for interacting with Nile databases:

Database Management

create-database

list-databases

get-database

delete-database

Credential Management

list-credentials

create-credential

Region Management

list-regions

SQL Query Execution

execute-sql

Resource Management

read-resource

list-resources

Tenant Management

list-tenants

create-tenant

delete-tenant

Example Usage

Here are some example commands you can use in Claude Desktop:

Response Format

All tools return responses in a standardized format:

Success responses include relevant data and confirmation messages

Error responses include detailed error messages and HTTP status codes

SQL query results are formatted as markdown tables

All responses are formatted for easy reading in Claude Desktop

Error Handling

The server handles various error scenarios:

Invalid API credentials

Network connectivity issues

Invalid database names or regions

Missing required parameters

Database operation failures

SQL syntax errors with helpful hints

Rate limiting and API restrictions

Troubleshooting

If Claude says it can't access the tools:

If database creation fails:

If credential operations fail:

Development

Project Structure

Key Files

server.ts: Main server implementation with tool registration and transport handling

tools.ts: Implementation of all database operations and SQL query execution

types.ts: TypeScript interfaces for database operations and responses

logger.ts: Structured logging with daily rotation and debug support

index.ts: Server startup and environment configuration

server.test.ts: Comprehensive test suite for all functionality

Development

Development Scripts

The following npm scripts are available:

npm run build: Compiles TypeScript to JavaScript

npm start: Starts the server in production mode

npm run dev: Starts the server in development mode with auto-rebuild

npm test: Runs the test suite

npm run lint: Runs ESLint for code quality checking

npm run clean: Removes build artifacts

Testing

The project includes a comprehensive test suite that covers:

Tool registration and schema validation

Database management operations

Connection string generation

SQL query execution and error handling

Response formatting and error cases

Run the tests with:

Logging

The server uses structured logging with the following features:

Daily rotating log files

Separate debug logs

JSON formatted logs with timestamps

Console output for development

Log categories: info, error, debug, api, sql, startup

License

MIT License - See LICENSE for details.

Features

Installation

Manual Installation

Starting the Server

Verifying the Server is Running

Configuration

Using with Claude Desktop

Setup

Using with Cursor

Setup

Server Modes

STDIO Mode (Default)

SSE Mode

Example Prompts

Database Management

Creating Tables

Querying Data

Schema Management

Available Tools

Database Management

Credential Management

Region Management

SQL Query Execution

Resource Management

Tenant Management

Example Usage

Response Format

Error Handling

Troubleshooting

Development

Project Structure

Key Files

Development

Development Scripts

Testing

Logging

License

Related Links

Features

Installation

Manual Installation

Starting the Server

Verifying the Server is Running

Configuration

Using with Claude Desktop

Setup

Using with Cursor

Setup

Server Modes

STDIO Mode (Default)

SSE Mode

Example Prompts

Database Management

Creating Tables

Querying Data

Schema Management

Available Tools

Database Management

Credential Management

Region Management

SQL Query Execution

Resource Management

Tenant Management

Example Usage

Response Format

Error Handling

Troubleshooting

Development

Project Structure

Key Files

Development

Development Scripts

Testing

Logging

License

Related Links

Related servers

MagicSlides MCP Server

Bitrefill