npm package: @nodusapi/mcp-server
Description: MCP server for NodusAPI - Enable LLMs to interact with your BaaS backend
Author: Alperen Cenky
Latest version: 1.8.4

# Nodus MCP Server

[![npm version](https://img.shields.io/npm/v/@nodusapi/mcp-server.svg)](https://www.npmjs.com/package/@nodusapi/mcp-server)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

![Nodus](https://raw.githubusercontent.com/alprncnky/noduspublic/main/first.png)

![Nodus Brand](https://raw.githubusercontent.com/alprncnky/noduspublic/main/second-brand.png)

## Introduction

Nodus MCP Server is a Model Context Protocol (MCP) server designed for **hobby project development**. It exposes your NodusAPI backend as MCP tools, allowing AI assistants like Claude to query and manipulate data in your tables, manage schemas, and handle project and API key operations through natural language.

**Note:** This project is currently in **TEST phase**. Features and APIs may change during development.

## Overview

Nodus MCP Server exposes your NodusAPI backend as MCP tools, allowing AI assistants like Claude to:

- Query and manipulate data in your tables
- Create and modify database schemas
- Manage projects and API keys
- Access table schemas as contextual resources

All through natural language conversations!

**Site Docs:** [https://nodusapi.com/en](https://nodusapi.com/en)

**App Dashboard:** [https://app.nodusapi.com](https://app.nodusapi.com)

![Nodus Dashboard](https://raw.githubusercontent.com/alprncnky/noduspublic/main/dashboard.png)

## Features

- **Data CRUD Operations**: List, get, create, update, and delete rows
- **Schema Management**: Create tables, add columns, update schemas
- **Project Management**: List projects, create new projects
- **Automatic Context**: Table schemas are automatically available to the LLM
- **Secure Authentication**: User-level API key works across all your projects
- **Safe by Design**: Destructive operations (delete tables, columns, projects) are not exposed
- **TypeScript**: Fully typed with comprehensive error handling

## Installation

### Quick Start (npx)

The easiest way to use Nodus MCP Server is with npx:

```bash
npx @nodusapi/mcp-server
```

### Global Installation

```bash
npm install -g @nodusapi/mcp-server
```

### Local Development

```bash
git clone https://github.com/yourusername/nodusmcp.git
cd nodusmcp
npm install
npm run build
```

## Configuration

### Option 1: Environment Variables (Recommended for Cursor)

Set these environment variables in your MCP client configuration:

```bash
NODUS_API_KEY=nds_your_api_key_here
NODUS_API_URL=http://api.nodus.com (optional, defaults to production)
```

**Note:** You don't need to specify a project slug. Use the `list_projects` tool to see your projects and `create_project` to create new ones.

### Option 2: Interactive Setup

If no configuration is found, the server will prompt you for:
- API Key
- API URL (defaults to http://api.nodus.com)

Configuration is saved to `~/.nodus-mcp/config.json` for future use. After connecting, use project management tools to list and create projects.

### Option 3: Manual Configuration

Create `~/.nodus-mcp/config.json`:

```json
{
  "apiKey": "nds_your_api_key_here",
  "apiUrl": "http://api.nodus.com"
}
```

## Cursor Integration

Add to your `.cursor/settings.json` or Cursor MCP settings:

```json
{
  "mcpServers": {
    "nodus": {
      "command": "npx",
      "args": ["-y", "@nodusapi/mcp-server"],
      "env": {
        "NODUS_API_KEY": "nds_your_api_key_here"
      }
    }
  }
}
```

After connecting, use the `list_projects` tool to see your projects.

Or use a local path during development:

```json
{
  "mcpServers": {
    "nodus": {
      "command": "node",
      "args": ["/absolute/path/to/nodusmcp/dist/index.js"],
      "env": {
        "NODUS_API_KEY": "nds_your_api_key_here"
      }
    }
  }
}
```

## Available Tools

### Data CRUD Tools

#### `list_rows`
List rows from a table with pagination and filtering.

**Parameters:**
- `tableSlug` (string, required): Table identifier
- `page` (number, optional): Page number (default: 1)
- `limit` (number, optional): Rows per page, max 100 (default: 20)
- `orderBy` (string, optional): Column to sort by
- `orderDir` (string, optional): Sort direction ('ASC' or 'DESC')
- `filters` (object, optional): Filter conditions (column: value pairs)

**Example:**
```
"Show me the first 10 users ordered by created date"
```

#### `get_row`
Get a single row by ID.

**Parameters:**
- `tableSlug` (string, required): Table identifier
- `id` (string, required): Row UUID

**Example:**
```
"Get the user with ID 123e4567-e89b-12d3-a456-426614174000"
```

#### `create_row`
Create a new row in a table.

**Parameters:**
- `tableSlug` (string, required): Table identifier
- `data` (object, required): Row data matching table schema

**Example:**
```
"Create a new user with name 'John Doe' and email 'john@example.com'"
```

#### `update_row`
Update an existing row.

**Parameters:**
- `tableSlug` (string, required): Table identifier
- `id` (string, required): Row UUID
- `data` (object, required): Partial row data to update

**Example:**
```
"Update user 123... and set their status to 'active'"
```

#### `delete_row`
Delete a row from a table.

**Parameters:**
- `tableSlug` (string, required): Table identifier
- `id` (string, required): Row UUID

**Example:**
```
"Delete the row with ID 123... from users table"
```

### Schema Management Tools

#### `list_tables`
List all tables in the project.

**Example:**
```
"Show me all my database tables"
```

#### `get_table_schema`
Get detailed schema for a specific table.

**Parameters:**
- `tableSlug` (string, required): Table identifier

**Example:**
```
"What columns does the users table have?"
```

#### `create_table`
Create a new table.

**Parameters:**
- `name` (string, required): Human-readable table name
- `slug` (string, required): Table slug (lowercase, numbers, underscores only)

**Example:**
```
"Create a new table called 'Products' with slug 'products'"
```

#### `update_table`
Update table name.

**Parameters:**
- `tableSlug` (string, required): Current table slug
- `name` (string, required): New table name

#### `add_column`
Add a new column to a table.

**Parameters:**
- `tableSlug` (string, required): Table identifier
- `name` (string, required): Column name
- `slug` (string, required): Column slug
- `type` (string, required): Column type (string, text, integer, float, boolean, datetime, json)
- `isRequired` (boolean, optional): Whether column is required
- `defaultValue` (any, optional): Default value

**Example:**
```
"Add a 'bio' column of type text to the users table"
```

#### `update_column`
Update column properties.

**Parameters:**
- `tableSlug` (string, required): Table identifier
- `columnSlug` (string, required): Column identifier
- `name` (string, optional): New column name
- `isRequired` (boolean, optional): Required status
- `defaultValue` (any, optional): Default value

### Project Management Tools

#### `list_projects`
List all projects for the authenticated user.

**Example:**
```
"Show me my projects"
```

#### `create_project`
Create a new project. The system automatically switches to the newly created project, so you can immediately start creating tables and managing data.

**Parameters:**
- `name` (string, required): Project name

**Example:**
```
"Create a new project called 'My Blog API'"
```

**Note:** After creation, you're automatically switched to this project. Your user-level API key works with it automatically.

### Endpoint Discovery

#### `list_all_endpoints`
List **all** available HTTP API endpoints for the current project. Returns both default CRUD endpoints (five per table: list, get, create, update, delete) and custom endpoints (user-defined serverless functions). Use this when you need to see the full set of API routes (e.g. to apply or document them).

**Parameters:** None.

**Example:**
```
"What API endpoints do I have?" / "List all my endpoints" / "Show me the endpoints I can use"
```

**Response:** Includes `projectSlug`, `tableEndpoints` (per-table CRUD paths), `customEndpoints` (fn paths), and a `summary`.

## Resources

### `nodus://schemas/tables`
Automatically provides the LLM with information about all tables and their schemas in your project.

## Usage Examples

### Example Conversation

```
User: "Show me all my database tables"
Assistant: [Calls list_tables tool]
"You have 3 tables: users, posts, and comments"

User: "What columns does the users table have?"
Assistant: [Calls get_table_schema with tableSlug: "users"]
"The users table has the following columns:
- id (string, required)
- name (string, required)
- email (string, required)
- bio (text, optional)
- created_at (datetime)"

User: "Create a new user named Alice with email alice@example.com"
Assistant: [Calls create_row with tableSlug: "users", data: {name: "Alice", email: "alice@example.com"}]
"Successfully created user Alice with ID abc-123..."

User: "List all users"
Assistant: [Calls list_rows with tableSlug: "users"]
"Found 5 users: Alice, Bob, Charlie, Diana, Eve"
```

## Security Notes

- **Safe by Design**: Destructive operations (delete tables, delete columns, delete projects) are NOT exposed through MCP for safety
- **API Key Security**: Store API keys securely using environment variables
- **Row-Level Operations**: Only individual row deletion is allowed (no bulk delete)
- **Validation**: All inputs are validated with Zod schemas
- **User-Level API Keys**: One API key works across all your projects

## Development

```bash
# Install dependencies
npm install

# Build
npm run build

# Development mode with auto-reload
npm run dev

# Run locally
npm start
```

## Troubleshooting

### "Cannot connect to Nodus API"
- Check your API URL (default: http://api.nodus.com)
- Verify network connectivity

### "Authentication failed"
- Verify your API key starts with `nds_`
- Generate a new API key from Nodus dashboard if needed

### "Access denied"
- Ensure your API key has necessary permissions
- Check if you're using the correct project ID

### "Resource not found"
- Verify table slug spelling
- Use `list_tables` to see available tables

## Requirements

- Node.js >= 18.0.0
- NodusAPI account with valid API key

## License

MIT

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## Support

- Documentation: https://docs.nodus.com
- Issues: https://github.com/nodusapi/nodusmcp/issues
- NodusAPI: https://nodus.com

## Related Projects

- [NodusAPI](https://github.com/nodusapi/nodusapi) - Backend-as-a-Service platform
- [NodusWeb](https://github.com/nodusapi/nodusweb) - Web dashboard for NodusAPI
- [Model Context Protocol](https://modelcontextprotocol.io) - MCP specification