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-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/
# 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 buildOther mcp package managers
There are several ways to start the server:
The server will start and listen for MCP protocol messages. You should see startup logs indicating:
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 successfully
If 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_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{
"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 directoryyour_api_key_here with your Nile API keyyour_workspace_slug with your Nile workspace slugnile-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.jsReplace:
your_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:
MCP_SERVER_MODE=sse in your .env filehttp://localhost:3000/ssehttp://localhost:3000/messagesExample 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, 'user@example.com', 'John Doe')
Show me all products in my_app database with price > 100
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
The server provides the following tools for interacting with Nile databases:
create-database
name (string): Name of the databaseregion (string): Either AWS_US_WEST_2 (Oregon) or AWS_EU_CENTRAL_1 (Frankfurt)list-databases
get-database
name (string): Name of the databasedelete-database
name (string): Name of the database to deletelist-credentials
databaseName (string): Name of the databasecreate-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 queryread-resource
databaseName (string): Name of the databaseresourceName (string): Name of the resource (table/view)list-resources
databaseName (string): Name of the databaselist-tenants
databaseName (string): Name of the databasecreate-tenant
databaseName (string): Name of the databasetenantName (string): Name for the new tenantdelete-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:password@us-west-2.db.thenile.dev: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 > 100
All tools return responses in a standardized format:
The server handles various error scenarios:
If Claude says it can't access the tools:
npm run build)If database creation fails:
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 configuration
server.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 test
The following npm scripts are available:
npm run build: Compiles TypeScript to JavaScriptnpm start: Starts the server in production modenpm run dev: Starts the server in development mode with auto-rebuildnpm test: Runs the test suitenpm run lint: Runs ESLint for code quality checkingnpm run clean: Removes build artifactsThe project includes a comprehensive test suite that covers:
Run the tests with:
The server uses structured logging with the following features:
MIT License - See LICENSE for details.
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4