MCP server for Nile Database - Manage and query databases, tenants, users, auth using LLMs
Learn more ↗️
Discord
?
Website
?
Issues
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.
Install the stable version:
npm install @niledatabase/nile-mcp-serverFor the latest alpha/preview version:
npm install @niledatabase/nile-mcp-server@alpha# 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 buildThere are several ways to start the server:
node dist/index.jsnpm run devThe 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.
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 successfullyIf you see these logs, the server is ready to accept commands from Claude Desktop.
Create a .env file in the root directory with your Nile credentials:
NILE_API_KEY=your_api_key_here
NILE_WORKSPACE_SLUG=your_workspace_slugTo 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.
npm run build{
"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
npm run buildnile-database (or any name you prefer)env NILE_API_KEY=your_key NILE_WORKSPACE_SLUG=your_workspace node /absolute/path/to/nile-mcp-server/dist/index.jsyour_key with your Nile API keyyour_workspace with your Nile workspace slug/absolute/path/to with the actual path to your projectThe server supports two operational modes:
The default mode uses standard input/output for communication, making it compatible with Claude Desktop and Cursor integrations.
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": {}
}'After setting up the MCP server in Cursor, you can use natural language to interact with Nile databases. Here are some example prompts:
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"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)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, '[email protected]', 'John Doe')
Show me all products in my_app database with price > 100Show 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_appThe server provides the following tools for interacting with Nile databases:
name (string): Name of the databaseregion (string): Either AWS_US_WEST_2 (Oregon) or AWS_EU_CENTRAL_1 (Frankfurt)Example: "Create a database named 'my-app' in AWS_US_WEST_2"
list-databases
Example: "List all my databases"
get-database
name (string): Name of the databaseExample: "Get details for database 'my-app'"
delete-database
name (string): Name of the database to deletedatabaseName (string): Name of the databaseExample: "List credentials for database 'my-app'"
create-credential
databaseName (string): Name of the databasedatabaseName (string): Name of the database to queryquery (string): SQL query to executeconnectionString (string, optional): Pre-existing connection string to use for the querydatabaseName (string): Name of the databaseresourceName (string): Name of the resource (table/view)Example: "Show me the schema for the users table in my-app"
list-resources
databaseName (string): Name of the databasedatabaseName (string): Name of the databaseExample: "Show all tenants in my-app database"
create-tenant
databaseName (string): Name of the databasetenantName (string): Name for the new tenantExample: "Create a tenant named 'acme-corp' in my-app"
delete-tenant
databaseName (string): Name of the databasetenantName (string): Name for the tenantHere are some example commands you can use in Claude Desktop:
# 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".
# Connection String Management
Get a connection string for database "my-app".
# Connection string format: postgres://<user>:<password>@<region>.db.thenile.dev:5432/<database>
# Example: postgres://cred-123:[email protected]:5432/my-app
# 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 > 100All 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
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
npm run build)Restart Claude Desktop
If database creation fails:
Verify the region is one of the supported options
If credential operations fail:
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 configurationserver.ts: Main server implementation with tool registration and transport handlingtools.ts: Implementation of all database operations and SQL query executiontypes.ts: TypeScript interfaces for database operations and responseslogger.ts: Structured logging with daily rotation and debug supportindex.ts: Server startup and environment configurationserver.test.ts: Comprehensive test suite for all functionality# Install dependencies
npm install
# Build the project
npm run build
# Start the server in production mode
node dist/index.js
# Start the server using npm script
npm start
# Start in development mode with auto-rebuild
npm run dev
# Run tests
npm testThe 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
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:
npm testThe 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
MIT License - See LICENSE for details.