{"id":26362256,"url":"https://github.com/niledatabase/nile-mcp-server","last_synced_at":"2026-01-24T10:53:04.816Z","repository":{"id":281725972,"uuid":"926987483","full_name":"niledatabase/nile-mcp-server","owner":"niledatabase","description":"MCP server for Nile Database - Manage and query databases, tenants, users, auth using LLMs","archived":false,"fork":false,"pushed_at":"2025-03-10T22:59:39.000Z","size":473,"stargazers_count":16,"open_issues_count":3,"forks_count":10,"subscribers_count":5,"default_branch":"alpha","last_synced_at":"2025-11-21T09:28:10.397Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/niledatabase.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-02-04T07:55:42.000Z","updated_at":"2025-08-21T20:25:06.000Z","dependencies_parsed_at":"2025-03-10T20:55:42.277Z","dependency_job_id":"788ee32b-bbed-49dc-8f02-aca7581f6a46","html_url":"https://github.com/niledatabase/nile-mcp-server","commit_stats":null,"previous_names":["niledatabase/nile-mcp-server"],"tags_count":23,"template":false,"template_full_name":null,"purl":"pkg:github/niledatabase/nile-mcp-server","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/niledatabase%2Fnile-mcp-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/niledatabase%2Fnile-mcp-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/niledatabase%2Fnile-mcp-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/niledatabase%2Fnile-mcp-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/niledatabase","download_url":"https://codeload.github.com/niledatabase/nile-mcp-server/tar.gz/refs/heads/alpha","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/niledatabase%2Fnile-mcp-server/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28725378,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-24T10:24:43.181Z","status":"ssl_error","status_checked_at":"2026-01-24T10:24:36.112Z","response_time":89,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-03-16T18:01:30.507Z","updated_at":"2026-01-24T10:53:04.811Z","avatar_url":"https://github.com/niledatabase.png","language":"TypeScript","funding_links":[],"categories":["Databases","Database \u0026 Messaging MCP Servers","Community Servers","MCP 服务器精选列表","Legend","پیاده‌سازی‌های سرور","Cloud Services","MCP Servers","🌐 Web Development","Uncategorized","Table of Contents","Data \u0026 Analytics"],"sub_categories":["Cloud Platforms","🗄️ 数据库交互","🗄️ \u003ca name=\"databases\"\u003e\u003c/a\u003eDatabases","🗄️ \u003ca name=\"databases\"\u003e\u003c/a\u003eپایگاه‌های داده","How to Submit","🗄️ Databases","Uncategorized","Databases"],"readme":"\u003cp align=\"center\"\u003e\n \u003ca href=\"https://thenile.dev\" target=\"_blank\"\u003e\u003cimg width=\"96px\" src=\"https://www.thenile.dev/about-logo.png\" /\u003e\u003c/a\u003e\n \u003ch2 align=\"center\"\u003eNile MCP Server\n  \u003cbr/\u003e\n  \u003cimg src=\"https://img.shields.io/npm/v/@niledatabase/server\"/\u003e\n \u003c/h2\u003e\n \u003cp align=\"center\"\u003e\n  \u003ca href=\"https://thenile.dev/docs/ai-embeddings/nile-mcp-server\"\u003e\u003cstrong\u003eLearn more ↗️\u003c/strong\u003e\u003c/a\u003e\n  \u003cbr /\u003e\n  \u003cbr /\u003e\n  \u003ca href=\"https://discord.gg/akRKRPKA\"\u003eDiscord\u003c/a\u003e\n  🔵\n  \u003ca href=\"https://thenile.dev\"\u003eWebsite\u003c/a\u003e\n  🔵 \n  \u003ca href=\"https://github.com/orgs/niledatabase/discussions\"\u003eIssues\u003c/a\u003e\n \u003c/p\u003e\n\u003c/p\u003e\n\n[![smithery badge](https://smithery.ai/badge/@niledatabase/nile-mcp-server)](https://smithery.ai/server/@niledatabase/nile-mcp-server)\n\nA Model Context Protocol (MCP) server implementation for Nile database platform. This server allows LLM applications to interact with Nile platform through a standardized interface.\n\n## Features\n\n- **Database Management**: Create, list, get details, and delete databases\n- **Credential Management**: Create and list database credentials\n- **Region Management**: List available regions for database creation\n- **SQL Query Support**: Execute SQL queries directly on Nile databases\n- **MCP Protocol Support**: Full implementation of the Model Context Protocol\n- **Type Safety**: Written in TypeScript with full type checking\n- **Error Handling**: Comprehensive error handling and user-friendly error messages\n- **Test Coverage**: Comprehensive test suite using Jest\n- **Environment Management**: Automatic loading of environment variables from .env file\n- **Input Validation**: Schema-based input validation using Zod\n\n## Installation\n\nInstall the stable version:\n```bash\nnpm install @niledatabase/nile-mcp-server\n```\n\nFor the latest alpha/preview version:\n```bash\nnpm install @niledatabase/nile-mcp-server@alpha\n```\nThis will install @niledatabase/nile-mcp-server in your node_modules folder. For example: node_modules/@niledatabase/nile-mcp-server/dist/\n\n### Manual Installation\n```bash\n# Clone the repository\ngit clone https://github.com/yourusername/nile-mcp-server.git\ncd nile-mcp-server\n\n# Install dependencies\nnpm install\n\n# Build the project\nnpm run build\n```\n### Other mcp package managers\n1. npx @michaellatman/mcp-get@latest install @niledatabase/nile-mcp-server\n\n## Starting the Server\n\nThere are several ways to start the server:\n\n1. **Direct Node Execution**:\n   ```bash\n   node dist/index.js\n   ```\n2. **Development Mode** (with auto-rebuild):\n   ```bash\n   npm run dev\n   ```\n\nThe server will start and listen for MCP protocol messages. You should see startup logs indicating:\n- Environment variables loaded\n- Server instance created\n- Tools initialized\n- Transport connection established\n\nTo stop the server, press `Ctrl+C`.\n\n### Verifying the Server is Running\n\nWhen the server starts successfully, you should see logs similar to:\n```\n[info] Starting Nile MCP Server...\n[info] Loading environment variables...\n[info] Environment variables loaded successfully\n[info] Creating server instance...\n[info] Tools initialized successfully\n[info] Setting up stdio transport...\n[info] Server started successfully\n```\n\nIf you see these logs, the server is ready to accept commands from Claude Desktop.\n\n## Configuration\n\nCreate a `.env` file in the root directory with your Nile credentials:\n\n```env\nNILE_API_KEY=your_api_key_here\nNILE_WORKSPACE_SLUG=your_workspace_slug\n```\n\nTo 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.\n\n## Using with Claude Desktop\n\n### Setup\n\n1. Install [Claude Desktop](https://claude.ai/desktop) if you haven't already\n2. Build the project:\n   ```bash\n   npm run build\n   ```\n3. Open Claude Desktop\n4. Go to Settings \u003e MCP Servers\n5. Click \"Add Server\"\n6. Add the following configuration:\n\n```json\n{\n  \"mcpServers\": {\n    \"nile-database\": {\n      \"command\": \"node\",\n      \"args\": [\n        \"/path/to/your/nile-mcp-server/dist/index.js\"\n      ],\n      \"env\": {\n        \"NILE_API_KEY\": \"your_api_key_here\",\n        \"NILE_WORKSPACE_SLUG\": \"your_workspace_slug\"\n      }\n    }\n  }\n}\n```\n\nReplace:\n- `/path/to/your/nile-mcp-server` with the absolute path to your project directory\n- `your_api_key_here` with your Nile API key\n- `your_workspace_slug` with your Nile workspace slug\n\n## Using with Cursor\n\n### Setup\n\n1. Install [Cursor](https://cursor.sh) if you haven't already\n2. Build the project:\n   ```bash\n   npm run build\n   ```\n3. Open Cursor\n4. Go to Settings (⌘,) \u003e Features \u003e MCP Servers\n5. Click \"Add New MCP Server\"\n6. Configure the server:\n   - Name: `nile-database` (or any name you prefer)\n   - Command: \n     ```bash\n     env NILE_API_KEY=your_key NILE_WORKSPACE_SLUG=your_workspace node /absolute/path/to/nile-mcp-server/dist/index.js\n     ```\n     Replace:\n     - `your_key` with your Nile API key\n     - `your_workspace` with your Nile workspace slug\n     - `/absolute/path/to` with the actual path to your project\n7. Click \"Save\"\n8. You should see a green indicator showing that the MCP server is connected\n9. Restart Cursor for the changes to take effect\n\n### Server Modes\n\nThe server supports two operational modes:\n\n#### STDIO Mode (Default)\nThe default mode uses standard input/output for communication, making it compatible with Claude Desktop and Cursor integrations.\n\n#### SSE Mode\nServer-Sent Events (SSE) mode enables real-time, event-driven communication over HTTP.\n\nTo enable SSE mode:\n1. Set `MCP_SERVER_MODE=sse` in your `.env` file\n2. The server will start an HTTP server (default port 3000)\n3. Connect to the SSE endpoint: `http://localhost:3000/sse`\n4. Send commands to: `http://localhost:3000/messages`\n\nExample SSE usage with curl:\n```bash\n# In terminal 1 - Listen for events\ncurl -N http://localhost:3000/sse\n\n# In terminal 2 - Send commands\ncurl -X POST http://localhost:3000/messages \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"type\": \"function\",\n    \"name\": \"list-databases\",\n    \"parameters\": {}\n  }'\n```\n\n### Example Prompts\n\nAfter setting up the MCP server in Cursor, you can use natural language to interact with Nile databases. Here are some example prompts:\n\n#### Database Management\n```\nCreate a new database named \"my_app\" in AWS_US_WEST_2 region\n\nList all my databases\n\nGet details for database \"my_app\"\n\nDelete database \"test_db\"\n```\n\n#### Creating Tables\n```\nCreate a users table in my_app database with columns:\n- tenant_id (UUID, references tenants)\n- id (INTEGER)\n- email (VARCHAR, unique per tenant)\n- name (VARCHAR)\n- created_at (TIMESTAMP)\n\nCreate a products table in my_app database with columns:\n- tenant_id (UUID, references tenants)\n- id (INTEGER)\n- name (VARCHAR)\n- price (DECIMAL)\n- description (TEXT)\n- created_at (TIMESTAMP)\n```\n\n#### Querying Data\n```\nExecute this query on my_app database:\nSELECT * FROM users WHERE tenant_id = 'your-tenant-id' LIMIT 5\n\nRun this query on my_app:\nINSERT INTO users (tenant_id, id, email, name) \nVALUES ('tenant-id', 1, 'user@example.com', 'John Doe')\n\nShow me all products in my_app database with price \u003e 100\n```\n\n#### Schema Management\n```\nShow me the schema for the users table in my_app database\n\nAdd a new column 'status' to the users table in my_app database\n\nCreate an index on the email column of the users table in my_app\n```\n\n### Available Tools\n\nThe server provides the following tools for interacting with Nile databases:\n\n#### Database Management\n\n1. **create-database**\n   - Creates a new Nile database\n   - Parameters:\n     - `name` (string): Name of the database\n     - `region` (string): Either `AWS_US_WEST_2` (Oregon) or `AWS_EU_CENTRAL_1` (Frankfurt)\n   - Returns: Database details including ID, name, region, and status\n   - Example: \"Create a database named 'my-app' in AWS_US_WEST_2\"\n\n2. **list-databases**\n   - Lists all databases in your workspace\n   - No parameters required\n   - Returns: List of databases with their IDs, names, regions, and status\n   - Example: \"List all my databases\"\n\n3. **get-database**\n   - Gets detailed information about a specific database\n   - Parameters:\n     - `name` (string): Name of the database\n   - Returns: Detailed database information including API host and DB host\n   - Example: \"Get details for database 'my-app'\"\n\n4. **delete-database**\n   - Deletes a database\n   - Parameters:\n     - `name` (string): Name of the database to delete\n   - Returns: Confirmation message\n   - Example: \"Delete database 'my-app'\"\n\n#### Credential Management\n\n1. **list-credentials**\n   - Lists all credentials for a database\n   - Parameters:\n     - `databaseName` (string): Name of the database\n   - Returns: List of credentials with IDs, usernames, and creation dates\n   - Example: \"List credentials for database 'my-app'\"\n\n2. **create-credential**\n   - Creates new credentials for a database\n   - Parameters:\n     - `databaseName` (string): Name of the database\n   - Returns: New credential details including username and one-time password\n   - Example: \"Create new credentials for database 'my-app'\"\n   - Note: Save the password when it's displayed, as it won't be shown again\n\n#### Region Management\n\n1. **list-regions**\n   - Lists all available regions for creating databases\n   - No parameters required\n   - Returns: List of available AWS regions\n   - Example: \"What regions are available for creating databases?\"\n\n#### SQL Query Execution\n\n1. **execute-sql**\n   - Executes SQL queries on a Nile database\n   - Parameters:\n     - `databaseName` (string): Name of the database to query\n     - `query` (string): SQL query to execute\n     - `connectionString` (string, optional): Pre-existing connection string to use for the query\n   - Returns: Query results formatted as a markdown table with column headers and row count\n   - Features:\n     - Automatic credential management (creates new if not specified)\n     - Secure SSL connection to database\n     - Results formatted as markdown tables\n     - Detailed error messages with hints\n     - Support for using existing connection strings\n   - Example: \"Execute SELECT * FROM users LIMIT 5 on database 'my-app'\"\n\n#### Resource Management\n\n1. **read-resource**\n   - Reads schema information for database resources (tables, views, etc.)\n   - Parameters:\n     - `databaseName` (string): Name of the database\n     - `resourceName` (string): Name of the resource (table/view)\n   - Returns: Detailed schema information including:\n     - Column names and types\n     - Primary keys and indexes\n     - Foreign key relationships\n     - Column descriptions and constraints\n   - Example: \"Show me the schema for the users table in my-app\"\n\n2. **list-resources**\n   - Lists all resources (tables, views) in a database\n   - Parameters:\n     - `databaseName` (string): Name of the database\n   - Returns: List of all resources with their types\n   - Example: \"List all tables in my-app database\"\n\n#### Tenant Management\n\n1. **list-tenants**\n   - Lists all tenants in a database\n   - Parameters:\n     - `databaseName` (string): Name of the database\n   - Returns: List of tenants with their IDs and metadata\n   - Example: \"Show all tenants in my-app database\"\n\n2. **create-tenant**\n   - Creates a new tenant in a database\n   - Parameters:\n     - `databaseName` (string): Name of the database\n     - `tenantName` (string): Name for the new tenant\n   - Returns: New tenant details including ID\n   - Example: \"Create a tenant named 'acme-corp' in my-app\"\n\n3. **delete-tenant**\n   - Deletes tenants in the database\n   - Parameters:\n     - `databaseName` (string): Name of the database\n     - `tenantName` (string): Name for the tenant\n   - Returns: Success if the tenant is deleted\n   - Example: \"Delete tenant named 'acme-corp' in my-app\"\n\n### Example Usage\n\nHere are some example commands you can use in Claude Desktop:\n\n```\n# Database Management\nPlease create a new database named \"my-app\" in the AWS_US_WEST_2 region.\nCan you list all my databases?\nGet the details for database \"my-app\".\nDelete the database named \"test-db\".\n\n# Connection String Management\nGet a connection string for database \"my-app\".\n# Connection string format: postgres://\u003cuser\u003e:\u003cpassword\u003e@\u003cregion\u003e.db.thenile.dev:5432/\u003cdatabase\u003e\n# Example: postgres://cred-123:password@us-west-2.db.thenile.dev:5432/my-app\n\n# SQL Queries\nExecute SELECT * FROM users LIMIT 5 on database \"my-app\"\nRun this query on my-app database: SELECT COUNT(*) FROM orders WHERE status = 'completed'\nUsing connection string \"postgres://user:pass@host:5432/db\", execute this query on my-app: SELECT * FROM products WHERE price \u003e 100\n```\n\n### Response Format\n\nAll tools return responses in a standardized format:\n- Success responses include relevant data and confirmation messages\n- Error responses include detailed error messages and HTTP status codes\n- SQL query results are formatted as markdown tables\n- All responses are formatted for easy reading in Claude Desktop\n\n### Error Handling\n\nThe server handles various error scenarios:\n- Invalid API credentials\n- Network connectivity issues\n- Invalid database names or regions\n- Missing required parameters\n- Database operation failures\n- SQL syntax errors with helpful hints\n- Rate limiting and API restrictions\n\n### Troubleshooting\n\n1. If Claude says it can't access the tools:\n   - Check that the server path in the configuration is correct\n   - Ensure the project is built (`npm run build`)\n   - Verify your API key and workspace slug are correct\n   - Restart Claude Desktop\n\n2. If database creation fails:\n   - Check your API key permissions\n   - Ensure the database name is unique in your workspace\n   - Verify the region is one of the supported options\n\n3. If credential operations fail:\n   - Verify the database exists and is in the READY state\n   - Check that your API key has the necessary permissions\n\n## Development\n\n### Project Structure\n\n```\nnile-mcp-server/\n├── src/\n│   ├── server.ts      # MCP server implementation\n│   ├── tools.ts       # Tool implementations\n│   ├── types.ts       # Type definitions\n│   ├── logger.ts      # Logging utilities\n│   ├── index.ts       # Entry point\n│   └── __tests__/     # Test files\n│       └── server.test.ts\n├── dist/             # Compiled JavaScript\n├── logs/            # Log files directory\n├── .env             # Environment configuration\n├── .gitignore       # Git ignore file\n├── package.json     # Project dependencies\n└── tsconfig.json    # TypeScript configuration\n```\n\n### Key Files\n\n- `server.ts`: Main server implementation with tool registration and transport handling\n- `tools.ts`: Implementation of all database operations and SQL query execution\n- `types.ts`: TypeScript interfaces for database operations and responses\n- `logger.ts`: Structured logging with daily rotation and debug support\n- `index.ts`: Server startup and environment configuration\n- `server.test.ts`: Comprehensive test suite for all functionality\n\n### Development\n\n```bash\n# Install dependencies\nnpm install\n\n# Build the project\nnpm run build\n\n# Start the server in production mode\nnode dist/index.js\n\n# Start the server using npm script\nnpm start\n\n# Start in development mode with auto-rebuild\nnpm run dev\n\n# Run tests\nnpm test\n```\n\n### Development Scripts\n\nThe following npm scripts are available:\n- `npm run build`: Compiles TypeScript to JavaScript\n- `npm start`: Starts the server in production mode\n- `npm run dev`: Starts the server in development mode with auto-rebuild\n- `npm test`: Runs the test suite\n- `npm run lint`: Runs ESLint for code quality checking\n- `npm run clean`: Removes build artifacts\n\n### Testing\n\nThe project includes a comprehensive test suite that covers:\n- Tool registration and schema validation\n- Database management operations\n- Connection string generation\n- SQL query execution and error handling\n- Response formatting and error cases\n\nRun the tests with:\n```bash\nnpm test\n```\n\n### Logging\n\nThe server uses structured logging with the following features:\n- Daily rotating log files\n- Separate debug logs\n- JSON formatted logs with timestamps\n- Console output for development\n- Log categories: info, error, debug, api, sql, startup\n\n## License\n\nMIT License - See [LICENSE](LICENSE) for details.\n\n## Related Links\n\n- [Model Context Protocol](https://modelcontextprotocol.io)\n- [Nile Database](https://thenile.dev)\n- [Claude Desktop](https://claude.ai/desktop)\n- [Cursor](https://cursor.sh) \n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fniledatabase%2Fnile-mcp-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fniledatabase%2Fnile-mcp-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fniledatabase%2Fnile-mcp-server/lists"}