<p align="center">
<a href="https://thenile.dev" target="_blank"></a>
<h2 align="center">Nile MCP Server
<br/>

</h2>
<p align="center">
<a href="https://thenile.dev/docs/ai-embeddings/nile-mcp-server"><strong>Learn more ↗️</strong></a>
<br />
<br />
<a href="https://discord.gg/akRKRPKA">Discord</a>
🔵
<a href="https://thenile.dev">Website</a>
🔵
<a href="https://github.com/orgs/niledatabase/discussions">Issues</a>
</p>
</p>

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:

npm install @niledatabase/nile-mcp-server

For the latest alpha/preview version:

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

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

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

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

Starting the Server

There are 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. 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:

[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

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:

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, click Workspaces in the top-left, select your workspace, and navigate to the Security section in the left menu.

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"
6. 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:
- your_key with your Nile API key
- your_workspace with your Nile workspace slug
- /absolute/path/to with the actual path to your project
7. Click "Save"
8. You should see a green indicator showing that the MCP server is connected
9. 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:
1. Set MCP_SERVER_MODE=sse in your .env file
2. The server will start an HTTP server (default port 3000)
3. Connect to the SSE endpoint: http://localhost:3000/sse
4. Send commands to: http://localhost:3000/messages

Example SSE usage with curl:

# In terminal 1 - Listen for events

curl -N http://localhost:3000/sse

In 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

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

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)
Create a products table in my_app database with columns:

- tenant_id (UUID, references tenants)

- id (INTEGER)

- name (VARCHAR)

- price (DECIMAL)

- description (TEXT)

- created_at (TIMESTAMP)

Querying Data

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

INSERT INTO users (tenant_id, id, email, name) 

VALUES ('tenant-id', 1, 'user@example.com', 'John Doe')
Show me all products in my_app database with price > 100

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

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

Database Management

1. create-database
- Creates a new Nile database
- Parameters:
- name (string): Name of the database
- region (string): Either AWS_US_WEST_2 (Oregon) or AWS_EU_CENTRAL_1 (Frankfurt)
- Returns: Database details including ID, name, region, and status
- Example: "Create a database named 'my-app' in AWS_US_WEST_2"

…