Nile MCP Server

1<p align="center">
2 <a href="https://thenile.dev" target="_blank"><img width="96px" src="https://www.thenile.dev/about-logo.png" /></a>
3 <h2 align="center">Nile MCP Server
4  <br/>
5  <img src="https://img.shields.io/npm/v/@niledatabase/server"/>
6 </h2>
7 <p align="center">
8  <a href="https://thenile.dev/docs/ai-embeddings/nile-mcp-server"><strong>Learn more ↗️</strong></a>
9  <br />
10  <br />
11  <a href="https://discord.gg/akRKRPKA">Discord</a>
12  🔵
13  <a href="https://thenile.dev">Website</a>
14  🔵 
15  <a href="https://github.com/orgs/niledatabase/discussions">Issues</a>
16 </p>
17</p>
18 
19[![smithery badge](https://smithery.ai/badge/@niledatabase/nile-mcp-server)](https://smithery.ai/server/@niledatabase/nile-mcp-server)
20 
21A Model Context Protocol (MCP) server implementation for Nile database platform. This server allows LLM applications to interact with Nile platform through a standardized interface.
22 
23## Features
24 
25- **Database Management**: Create, list, get details, and delete databases
26- **Credential Management**: Create and list database credentials
27- **Region Management**: List available regions for database creation
28- **SQL Query Support**: Execute SQL queries directly on Nile databases
29- **MCP Protocol Support**: Full implementation of the Model Context Protocol
30- **Type Safety**: Written in TypeScript with full type checking
31- **Error Handling**: Comprehensive error handling and user-friendly error messages
32- **Test Coverage**: Comprehensive test suite using Jest
33- **Environment Management**: Automatic loading of environment variables from .env file
34- **Input Validation**: Schema-based input validation using Zod
35 
36## Installation
37 
38Install the stable version:
39```bash
40npm install @niledatabase/nile-mcp-server
41```
42 
43For the latest alpha/preview version:
44```bash
45npm install @niledatabase/nile-mcp-server@alpha
46```
47This will install @niledatabase/nile-mcp-server in your node_modules folder. For example: node_modules/@niledatabase/nile-mcp-server/dist/
48 
49### Manual Installation
50```bash
51# Clone the repository
52git clone https://github.com/yourusername/nile-mcp-server.git
53cd nile-mcp-server
54 
55# Install dependencies
56npm install
57 
58# Build the project
59npm run build
60```
61### Other mcp package managers
621. npx @michaellatman/mcp-get@latest install @niledatabase/nile-mcp-server
63 
64## Starting the Server
65 
66There are several ways to start the server:
67 
681. **Direct Node Execution**:
69   ```bash
70   node dist/index.js
71   ```
722. **Development Mode** (with auto-rebuild):
73   ```bash
74   npm run dev
75   ```
76 
77The server will start and listen for MCP protocol messages. You should see startup logs indicating:
78- Environment variables loaded
79- Server instance created
80- Tools initialized
81- Transport connection established
82 
83To stop the server, press `Ctrl+C`.
84 
85### Verifying the Server is Running
86 
87When the server starts successfully, you should see logs similar to:
88```
89[info] Starting Nile MCP Server...
90[info] Loading environment variables...
91[info] Environment variables loaded successfully
92[info] Creating server instance...
93[info] Tools initialized successfully
94[info] Setting up stdio transport...
95[info] Server started successfully
96```
97 
98If you see these logs, the server is ready to accept commands from Claude Desktop.
99 
100## Configuration
101 
102Create a `.env` file in the root directory with your Nile credentials:
103 
104```env
105NILE_API_KEY=your_api_key_here
106NILE_WORKSPACE_SLUG=your_workspace_slug
107```
108 
109To create a Nile API key, log in to your [Nile account](console.thenile.dev), click Workspaces in the top-left, select your workspace, and navigate to the Security section in the left menu.
110 
111## Using with Claude Desktop
112 
113### Setup
114 
1151. Install [Claude Desktop](https://claude.ai/desktop) if you haven't already
1162. Build the project:
117   ```bash
118   npm run build
119   ```
1203. Open Claude Desktop
1214. Go to Settings > MCP Servers
1225. Click "Add Server"
1236. Add the following configuration:
124 
125```json
126{
127  "mcpServers": {
128    "nile-database": {
129      "command": "node",
130      "args": [
131        "/path/to/your/nile-mcp-server/dist/index.js"
132      ],
133      "env": {
134        "NILE_API_KEY": "your_api_key_here",
135        "NILE_WORKSPACE_SLUG": "your_workspace_slug"
136      }
137    }
138  }
139}
140```
141 
142Replace:
143- `/path/to/your/nile-mcp-server` with the absolute path to your project directory
144- `your_api_key_here` with your Nile API key
145- `your_workspace_slug` with your Nile workspace slug
146 
147## Using with Cursor
148 
149### Setup
150 
1511. Install [Cursor](https://cursor.sh) if you haven't already
1522. Build the project:
153   ```bash
154   npm run build
155   ```
1563. Open Cursor
1574. Go to Settings (⌘,) > Features > MCP Servers
1585. Click "Add New MCP Server"
1596. Configure the server:
160   - Name: `nile-database` (or any name you prefer)
161   - Command: 
162     ```bash
163     env NILE_API_KEY=your_key NILE_WORKSPACE_SLUG=your_workspace node /absolute/path/to/nile-mcp-server/dist/index.js
164     ```
165     Replace:
166     - `your_key` with your Nile API key
167     - `your_workspace` with your Nile workspace slug
168     - `/absolute/path/to` with the actual path to your project
1697. Click "Save"
1708. You should see a green indicator showing that the MCP server is connected
1719. Restart Cursor for the changes to take effect
172 
173### Server Modes
174 
175The server supports two operational modes:
176 
177#### STDIO Mode (Default)
178The default mode uses standard input/output for communication, making it compatible with Claude Desktop and Cursor integrations.
179 
180#### SSE Mode
181Server-Sent Events (SSE) mode enables real-time, event-driven communication over HTTP.
182 
183To enable SSE mode:
1841. Set `MCP_SERVER_MODE=sse` in your `.env` file
1852. The server will start an HTTP server (default port 3000)
1863. Connect to the SSE endpoint: `http://localhost:3000/sse`
1874. Send commands to: `http://localhost:3000/messages`
188 
189Example SSE usage with curl:
190```bash
191# In terminal 1 - Listen for events
192curl -N http://localhost:3000/sse
193 
194# In terminal 2 - Send commands
195curl -X POST http://localhost:3000/messages \
196  -H "Content-Type: application/json" \
197  -d '{
198    "type": "function",
199    "name": "list-databases",
200    "parameters": {}
201  }'
202```
203 
204### Example Prompts
205 
206After setting up the MCP server in Cursor, you can use natural language to interact with Nile databases. Here are some example prompts:
207 
208#### Database Management
209```
210Create a new database named "my_app" in AWS_US_WEST_2 region
211 
212List all my databases
213 
214Get details for database "my_app"
215 
216Delete database "test_db"
217```
218 
219#### Creating Tables
220```
221Create a users table in my_app database with columns:
222- tenant_id (UUID, references tenants)
223- id (INTEGER)
224- email (VARCHAR, unique per tenant)
225- name (VARCHAR)
226- created_at (TIMESTAMP)
227 
228Create a products table in my_app database with columns:
229- tenant_id (UUID, references tenants)
230- id (INTEGER)
231- name (VARCHAR)
232- price (DECIMAL)
233- description (TEXT)
234- created_at (TIMESTAMP)
235```
236 
237#### Querying Data
238```
239Execute this query on my_app database:
240SELECT * FROM users WHERE tenant_id = 'your-tenant-id' LIMIT 5
241 
242Run this query on my_app:
243INSERT INTO users (tenant_id, id, email, name) 
244VALUES ('tenant-id', 1, 'user@example.com', 'John Doe')
245 
246Show me all products in my_app database with price > 100
247```
248 
249#### Schema Management
250```
251Show me the schema for the users table in my_app database
252 
253Add a new column 'status' to the users table in my_app database
254 
255Create an index on the email column of the users table in my_app
256```
257 
258### Available Tools
259 
260The server provides the following tools for interacting with Nile databases:
261 
262#### Database Management
263 
2641. **create-database**
265   - Creates a new Nile database
266   - Parameters:
267     - `name` (string): Name of the database
268     - `region` (string): Either `AWS_US_WEST_2` (Oregon) or `AWS_EU_CENTRAL_1` (Frankfurt)
269   - Returns: Database details including ID, name, region, and status
270   - Example: "Create a database named 'my-app' in AWS_US_WEST_2"
271 
2722. **list-databases**
273   - Lists all databases in your workspace
274   - No parameters required
275   - Returns: List of databases with their IDs, names, regions, and status
276   - Example: "List all my databases"
277 
2783. **get-database**
279   - Gets detailed information about a specific database
280   - Parameters:
281     - `name` (string): Name of the database
282   - Returns: Detailed database information including API host and DB host
283   - Example: "Get details for database 'my-app'"
284 
2854. **delete-database**
286   - Deletes a database
287   - Parameters:
288     - `name` (string): Name of the database to delete
289   - Returns: Confirmation message
290   - Example: "Delete database 'my-app'"
291 
292#### Credential Management
293 
2941. **list-credentials**
295   - Lists all credentials for a database
296   - Parameters:
297     - `databaseName` (string): Name of the database
298   - Returns: List of credentials with IDs, usernames, and creation dates
299   - Example: "List credentials for database 'my-app'"
300 
3012. **create-credential**
302   - Creates new credentials for a database
303   - Parameters:
304     - `databaseName` (string): Name of the database
305   - Returns: New credential details including username and one-time password
306   - Example: "Create new credentials for database 'my-app'"
307   - Note: Save the password when it's displayed, as it won't be shown again
308 
309#### Region Management
310 
3111. **list-regions**
312   - Lists all available regions for creating databases
313   - No parameters required
314   - Returns: List of available AWS regions
315   - Example: "What regions are available for creating databases?"
316 
317#### SQL Query Execution
318 
3191. **execute-sql**
320   - Executes SQL queries on a Nile database
321   - Parameters:
322     - `databaseName` (string): Name of the database to query
323     - `query` (string): SQL query to execute
324     - `connectionString` (string, optional): Pre-existing connection string to use for the query
325   - Returns: Query results formatted as a markdown table with column headers and row count
326   - Features:
327     - Automatic credential management (creates new if not specified)
328     - Secure SSL connection to database
329     - Results formatted as markdown tables
330     - Detailed error messages with hints
331     - Support for using existing connection strings
332   - Example: "Execute SELECT * FROM users LIMIT 5 on database 'my-app'"
333 
334#### Resource Management
335 
3361. **read-resource**
337   - Reads schema information for database resources (tables, views, etc.)
338   - Parameters:
339     - `databaseName` (string): Name of the database
340     - `resourceName` (string): Name of the resource (table/view)
341   - Returns: Detailed schema information including:
342     - Column names and types
343     - Primary keys and indexes
344     - Foreign key relationships
345     - Column descriptions and constraints
346   - Example: "Show me the schema for the users table in my-app"
347 
3482. **list-resources**
349   - Lists all resources (tables, views) in a database
350   - Parameters:
351     - `databaseName` (string): Name of the database
352   - Returns: List of all resources with their types
353   - Example: "List all tables in my-app database"
354 
355#### Tenant Management
356 
3571. **list-tenants**
358   - Lists all tenants in a database
359   - Parameters:
360     - `databaseName` (string): Name of the database
361   - Returns: List of tenants with their IDs and metadata
362   - Example: "Show all tenants in my-app database"
363 
3642. **create-tenant**
365   - Creates a new tenant in a database
366   - Parameters:
367     - `databaseName` (string): Name of the database
368     - `tenantName` (string): Name for the new tenant
369   - Returns: New tenant details including ID
370   - Example: "Create a tenant named 'acme-corp' in my-app"
371 
3723. **delete-tenant**
373   - Deletes tenants in the database
374   - Parameters:
375     - `databaseName` (string): Name of the database
376     - `tenantName` (string): Name for the tenant
377   - Returns: Success if the tenant is deleted
378   - Example: "Delete tenant named 'acme-corp' in my-app"
379 
380### Example Usage
381 
382Here are some example commands you can use in Claude Desktop:
383 
384```
385# Database Management
386Please create a new database named "my-app" in the AWS_US_WEST_2 region.
387Can you list all my databases?
388Get the details for database "my-app".
389Delete the database named "test-db".
390 
391# Connection String Management
392Get a connection string for database "my-app".
393# Connection string format: postgres://<user>:<password>@<region>.db.thenile.dev:5432/<database>
394# Example: postgres://cred-123:password@us-west-2.db.thenile.dev:5432/my-app
395 
396# SQL Queries
397Execute SELECT * FROM users LIMIT 5 on database "my-app"
398Run this query on my-app database: SELECT COUNT(*) FROM orders WHERE status = 'completed'
399Using connection string "postgres://user:pass@host:5432/db", execute this query on my-app: SELECT * FROM products WHERE price > 100
400```
401 
402### Response Format
403 
404All tools return responses in a standardized format:
405- Success responses include relevant data and confirmation messages
406- Error responses include detailed error messages and HTTP status codes
407- SQL query results are formatted as markdown tables
408- All responses are formatted for easy reading in Claude Desktop
409 
410### Error Handling
411 
412The server handles various error scenarios:
413- Invalid API credentials
414- Network connectivity issues
415- Invalid database names or regions
416- Missing required parameters
417- Database operation failures
418- SQL syntax errors with helpful hints
419- Rate limiting and API restrictions
420 
421### Troubleshooting
422 
4231. If Claude says it can't access the tools:
424   - Check that the server path in the configuration is correct
425   - Ensure the project is built (`npm run build`)
426   - Verify your API key and workspace slug are correct
427   - Restart Claude Desktop
428 
4292. If database creation fails:
430   - Check your API key permissions
431   - Ensure the database name is unique in your workspace
432   - Verify the region is one of the supported options
433 
4343. If credential operations fail:
435   - Verify the database exists and is in the READY state
436   - Check that your API key has the necessary permissions
437 
438## Development
439 
440### Project Structure
441 
442```
443nile-mcp-server/
444├── src/
445│   ├── server.ts      # MCP server implementation
446│   ├── tools.ts       # Tool implementations
447│   ├── types.ts       # Type definitions
448│   ├── logger.ts      # Logging utilities
449│   ├── index.ts       # Entry point
450│   └── __tests__/     # Test files
451│       └── server.test.ts
452├── dist/             # Compiled JavaScript
453├── logs/            # Log files directory
454├── .env             # Environment configuration
455├── .gitignore       # Git ignore file
456├── package.json     # Project dependencies
457└── tsconfig.json    # TypeScript configuration
458```
459 
460### Key Files
461 
462- `server.ts`: Main server implementation with tool registration and transport handling
463- `tools.ts`: Implementation of all database operations and SQL query execution
464- `types.ts`: TypeScript interfaces for database operations and responses
465- `logger.ts`: Structured logging with daily rotation and debug support
466- `index.ts`: Server startup and environment configuration
467- `server.test.ts`: Comprehensive test suite for all functionality
468 
469### Development
470 
471```bash
472# Install dependencies
473npm install
474 
475# Build the project
476npm run build
477 
478# Start the server in production mode
479node dist/index.js
480 
481# Start the server using npm script
482npm start
483 
484# Start in development mode with auto-rebuild
485npm run dev
486 
487# Run tests
488npm test
489```
490 
491### Development Scripts
492 
493The following npm scripts are available:
494- `npm run build`: Compiles TypeScript to JavaScript
495- `npm start`: Starts the server in production mode
496- `npm run dev`: Starts the server in development mode with auto-rebuild
497- `npm test`: Runs the test suite
498- `npm run lint`: Runs ESLint for code quality checking
499- `npm run clean`: Removes build artifacts
500 
501### Testing
502 
503The project includes a comprehensive test suite that covers:
504- Tool registration and schema validation
505- Database management operations
506- Connection string generation
507- SQL query execution and error handling
508- Response formatting and error cases
509 
510Run the tests with:
511```bash
512npm test
513```
514 
515### Logging
516 
517The server uses structured logging with the following features:
518- Daily rotating log files
519- Separate debug logs
520- JSON formatted logs with timestamps
521- Console output for development
522- Log categories: info, error, debug, api, sql, startup
523 
524## License
525 
526MIT License - See [LICENSE](LICENSE) for details.
527 
528## Related Links
529 
530- [Model Context Protocol](https://modelcontextprotocol.io)
531- [Nile Database](https://thenile.dev)
532- [Claude Desktop](https://claude.ai/desktop)
533- [Cursor](https://cursor.sh) 
534