Baasix MCP Server

⚠️ THIS REPOSITORY HAS MOVED ⚠️

This repository is no longer maintained. The project has been moved to a monorepo. ### 👉 New Repository: github.com/baasix/baasix New package name: @baasix/mcp The MCP Server is now part of the Baasix monorepo at packages/mcp. ``bash npm install @baasix/mcp ``

---

Baasix MCP Server

A Model Context Protocol (MCP) server that provides Claude Desktop and other MCP clients with direct access to Baasix Backend-as-a-Service operations.

Baasix is an open-source BaaS that generates REST APIs from data models, featuring 50+ filter operators, visual workflows, multi-tenancy, and real-time subscriptions.

Features

• 45+ MCP Tools for comprehensive Baasix operations
• Schema Management - Create, update, delete collections and relationships
• CRUD Operations - Full item management with powerful query capabilities
• 50+ Filter Operators - From basic comparison to geospatial and JSONB queries
• Relations - M2O, O2M, M2M, and polymorphic M2A relationships
• Aggregation - SUM, AVG, COUNT, MIN, MAX with groupBy
• Permissions - Role-based access control management
• File Management - Upload, list, and manage files
• Authentication - Login, register, magic links, invitations
• Multi-tenancy - Tenant management and switching
• Realtime - Enable/disable WAL-based realtime per collection

Quick Start

1. Install dependencies

cd mcp
npm install

2. Configure environment

cp .env.example .env
# Edit .env with your Baasix server details

3. Start the MCP server

npm start

Configuration

Environment Variables

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | BAASIX_URL | Yes | http://localhost:8056 | Baasix server URL | | BAASIX_AUTH_TOKEN | No | - | Pre-obtained JWT token | | BAASIX_EMAIL | No | - | Email for auto-authentication | | BAASIX_PASSWORD | No* | - | Password for auto-authentication |

*Either BAASIX_AUTH_TOKEN OR both BAASIX_EMAIL and BAASIX_PASSWORD must be provided.

Environment Files

• .env - Development environment (default)
• .env.production - Production environment

Available Scripts

• npm run development - Start with development environment
• npm start - Start with production environment
• npm run dev - Development mode with auto-restart
• npm test - Run tests
• npm run debug - Start with MCP inspector for debugging

IDE Integration

Baasix MCP Server integrates with various AI-powered development tools. Below are configuration examples for popular IDEs and tools.

Claude Desktop

Add to your Claude Desktop configuration (claude_desktop_config.json):

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "baasix": {
      "command": "node",
      "args": ["/path/to/baasix/mcp/server.js"],
      "env": {
        "BAASIX_URL": "http://localhost:8056",
        "BAASIX_EMAIL": "admin@baasix.com",
        "BAASIX_PASSWORD": "admin@123"
      }
    }
  }
}

Claude Code (Anthropic CLI)

For Claude Code CLI, create a .mcp.json file in your project root:

{
  "mcpServers": {
    "baasix": {
      "command": "node",
      "args": ["./mcp-server.js"],
      "env": {
        "BAASIX_URL": "http://localhost:8056",
        "BAASIX_EMAIL": "admin@baasix.com",
        "BAASIX_PASSWORD": "admin@123"
      }
    }
  }
}

Or add via CLI: ``bash claude mcp add baasix npm run start ``

VS Code with GitHub Copilot

For VS Code with GitHub Copilot, create .vscode/mcp.json in your project:

{
  "servers": {
    "baasix": {
      "type": "stdio",
      "command": "node",
      "args": ["./mcp-server.js"],
      "env": {
        "BAASIX_URL": "http://localhost:8056",
        "BAASIX_EMAIL": "admin@baasix.com",
        "BAASIX_PASSWORD": "admin@123"
      }
    }
  },
  "inputs": []
}

Cursor IDE

For Cursor, add to your Cursor settings or create a project-level configuration:

{
  "mcpServers": {
    "baasix": {
      "command": "node",
      "args": ["./mcp-server.js"],
      "env": {
        "BAASIX_URL": "http://localhost:8056",
        "BAASIX_EMAIL": "admin@baasix.com",
        "BAASIX_PASSWORD": "admin@123"
      }
    }
  }
}

Using the npm Package

If you're using the published npm package instead of the source:

{
  "mcpServers": {
    "baasix": {
      "command": "npx",
      "args": ["@tspvivek/baasix-mcp-server"],
      "env": {
        "BAASIX_URL": "http://localhost:8056",
        "BAASIX_EMAIL": "admin@baasix.com",
        "BAASIX_PASSWORD": "admin@123"
      }
    }
  }
}

Available Tools

Schema Management (13 tools)

| Tool | Description | |------|-------------| | baasix_list_schemas | List all collections with search/pagination | | baasix_get_schema | Get detailed schema for a collection | | baasix_create_schema | Create a new collection schema | | baasix_update_schema | Update existing schema | | baasix_delete_schema | Delete a collection schema | | baasix_add_index | Add index to collection | | baasix_remove_index | Remove index from collection | | baasix_migrate_indexes | Add missing FK indexes to all collections | | baasix_create_relationship | Create M2O/O2M/M2M/M2A relationship | | baasix_update_relationship | Update existing relationship | | baasix_delete_relationship | Delete a relationship | | baasix_export_schemas | Export all schemas as JSON | | baasix_import_schemas | Import schemas from JSON |

Item Management (5 tools)

| Tool | Description | |------|-------------| | baasix_list_items | Query items with filters, sort, pagination | | baasix_get_item | Get specific item by ID | | baasix_create_item | Create new item | | baasix_update_item | Update existing item | | baasix_delete_item | Delete item |

File Management (3 tools)

| Tool | Description | |------|-------------| | baasix_list_files | List files with metadata | | baasix_get_file_info | Get file details | | baasix_delete_file | Delete file |

Authentication (10 tools)

| Tool | Description | |------|-------------| | baasix_auth_status | Check authentication status | | baasix_refresh_auth | Refresh authentication token | | baasix_register_user | Register new user | | baasix_login | Login with email/password | | baasix_logout | Logout current user | | baasix_get_current_user | Get current user info | | baasix_send_invite | Send user invitation | | baasix_verify_invite | Verify invitation token | | baasix_send_magic_link | Send magic link/code | | baasix_get_user_tenants | Get user's available tenants | | baasix_switch_tenant | Switch tenant context |

Permissions (9 tools)

| Tool | Description | |------|-------------| | baasix_list_roles | List all roles | | baasix_list_permissions | List all permissions | | baasix_get_permission | Get permission by ID | | baasix_get_permissions | Get permissions for a role | | baasix_create_permission | Create new permission | | baasix_update_permission | Update permission | | baasix_delete_permission | Delete permission | | baasix_update_permissions | Bulk update role permissions | | baasix_reload_permissions | Reload permission cache |

Reports & Analytics (2 tools)

| Tool | Description | |------|-------------| | baasix_generate_report | Generate reports with grouping | | baasix_collection_stats | Get collection statistics |

Notifications (3 tools)

| Tool | Description | |------|-------------| | baasix_list_notifications | List user notifications | | baasix_send_notification | Send notification to users | | baasix_mark_notification_seen | Mark notification as seen |

Settings (2 tools)

| Tool | Description | |------|-------------| | baasix_get_settings | Get application settings | | baasix_update_settings | Update settings |

Realtime (5 tools)

| Tool | Description | |------|-------------| | baasix_realtime_status | Get realtime service status | | baasix_realtime_config | Check PostgreSQL WAL configuration | | baasix_realtime_collections | List collections with realtime enabled | | baasix_realtime_enable | Enable realtime for a collection | | baasix_realtime_disable | Disable realtime for a collection |

Utilities (2 tools)

| Tool | Description | |------|-------------| | baasix_server_info | Get server health/info | | baasix_sort_items | Reorder items in collection |

Filter Operators Reference

When using baasix_list_items, the filter parameter supports 50+ operators:

Comparison Operators

{"field": {"eq": "value"}}      // Equal
{"field": {"neq": "value"}}     // Not equal
{"field": {"gt": 100}}          // Greater than
{"field": {"gte": 100}}         // Greater than or equal
{"field": {"lt": 100}}          // Less than
{"field": {"lte": 100}}         // Less than or equal

String Operators

{"field": {"contains": "text"}}       // Contains substring
{"field": {"icontains": "text"}}      // Contains (case-insensitive)
{"field": {"startswith": "pre"}}      // Starts with
{"field": {"istartswith": "pre"}}     // Starts with (case-insensitive)
{"field": {"endswith": "fix"}}        // Ends with
{"field": {"iendswith": "fix"}}       // Ends with (case-insensitive)
{"field": {"like": "pat%tern"}}       // SQL LIKE pattern
{"field": {"ilike": "pat%tern"}}      // LIKE (case-insensitive)
{"field": {"regex": "^\\d+$"}}        // Regular expression
{"field": {"iregex": "pattern"}}      // Regex (case-insensitive)

Null/Empty Operators

{"field": {"isNull": true}}           // IS NULL
{"field": {"isNull": false}}          // IS NOT NULL
{"field": {"empty": true}}            // Empty string or null
{"field": {"empty": false}}           // Not empty

List Operators

{"field": {"in": ["a", "b", "c"]}}    // In list
{"field": {"nin": ["x", "y"]}}        // Not in list
{"field": {"between": [10, 100]}}     // Between range
{"field": {"nbetween": [10, 100]}}    // Not between

Array Operators

{"tags": {"arraycontains": ["a", "b"]}}    // Contains all elements
{"tags": {"arraycontainsany": ["a", "b"]}} // Contains any element
{"tags": {"arraylength": 3}}               // Array has exact length
{"tags": {"arrayempty": true}}             // Array is empty

JSONB Operators (PostgreSQL)

{"meta": {"jsoncontains": {"key": "val"}}}      // JSON contains
{"meta": {"jsoncontainedby": {"a": 1}}}         // JSON contained by
{"meta": {"jsonhaskey": "key"}}                 // Has key
{"meta": {"jsonhasanykeys": ["a", "b"]}}        // Has any keys
{"meta": {"jsonhasallkeys": ["a", "b"]}}        // Has all keys
{"meta": {"jsonpath": "$.store.book[0].title"}} // JSONPath query

Geospatial Operators (PostGIS)

{"location": {"dwithin": {"geometry": {"type": "Point", "coordinates": [-73.9, 40.7]}, "distance": 5000}}}
{"location": {"intersects": {"type": "Polygon", "coordinates": [...]}}}
{"location": {"contains": {"type": "Point", "coordinates": [...]}}}
{"location": {"within": {"type": "Polygon", "coordinates": [...]}}}
{"location": {"overlaps": {"type": "Polygon", "coordinates": [...]}}}

Logical Operators

{"AND": [{"status": {"eq": "active"}}, {"price": {"lt": 100}}]}
{"OR": [{"type": {"eq": "A"}}, {"type": {"eq": "B"}}]}
{"NOT": {"deleted": {"eq": true}}}

Dynamic Variables

{"author_Id": {"eq": "$CURRENT_USER"}}    // Current user's ID
{"createdAt": {"gte": "$NOW"}}            // Current timestamp
{"createdAt": {"gte": "$NOW-DAYS_7"}}     // 7 days ago
{"dueDate": {"lte": "$NOW+MONTHS_1"}}     // 1 month from now

Relation Filtering

// Filter by related collection fields
{"category.name": {"eq": "Electronics"}}
{"author.role.name": {"eq": "admin"}}

Query Parameters for baasix_list_items

{
  collection: "products",           // Required: collection name
  filter: {...},                    // Filter object (see above)
  sort: "createdAt:desc",          // Sort: "field:asc" or "field:desc"
  page: 1,                         // Page number
  limit: 10,                       // Items per page (-1 for all)
  fields: ["*", "category.*"],     // Fields to include (* for all)
  search: "keyword",               // Full-text search
  searchFields: ["name", "desc"],  // Fields to search in
  aggregate: {                     // Aggregation functions
    total: {function: "sum", field: "price"},
    count: {function: "count", field: "id"}
  },
  groupBy: ["category_Id"],        // Group by fields
  relConditions: {                 // Filter related records
    "reviews": {"approved": {"eq": true}}
  }
}

Schema Definition Example

When using baasix_create_schema:

{
  collection: "products",
  schema: {
    name: "Product",
    timestamps: true,        // Adds createdAt, updatedAt
    paranoid: false,         // Set true for soft deletes
    fields: {
      id: {
        type: "UUID",
        primaryKey: true,
        defaultValue: {type: "UUIDV4"}
      },
      sku: {
        type: "SUID",
        unique: true,
        defaultValue: {type: "SUID"}
      },
      name: {
        type: "String",
        allowNull: false,
        values: {length: 255},
        validate: {notEmpty: true, len: [3, 255]}
      },
      price: {
        type: "Decimal",
        values: {precision: 10, scale: 2},
        defaultValue: 0.00,
        validate: {min: 0, max: 999999.99}
      },
      quantity: {
        type: "Integer",
        defaultValue: 0,
        validate: {isInt: true, min: 0}
      },
      email: {
        type: "String",
        validate: {isEmail: true}
      },
      tags: {
        type: "Array",
        values: {type: "String"},
        defaultValue: []
      },
      metadata: {
        type: "JSONB",
        defaultValue: {}
      }
    }
  }
}

Field Validation Rules

| Rule | Type | Description | |------|------|-------------| | min | number | Minimum value for numeric fields | | max | number | Maximum value for numeric fields | | isInt | boolean | Validate as integer | | notEmpty | boolean | String cannot be empty | | isEmail | boolean | Valid email format | | isUrl | boolean | Valid URL format | | len | [min, max] | String length range | | is / matches | regex | Pattern matching |

// Validation examples
{
  "email": {
    "type": "String",
    "validate": {"isEmail": true, "notEmpty": true}
  },
  "age": {
    "type": "Integer",
    "validate": {"isInt": true, "min": 0, "max": 120}
  },
  "username": {
    "type": "String",
    "validate": {"notEmpty": true, "len": [3, 50]}
  },
  "phone": {
    "type": "String",
    "validate": {"matches": "^\\+?[1-9]\\d{1,14}$"}
  }
}

Default Value Types

| Type | Description | |------|-------------| | UUIDV4 | Random UUID v4 | | SUID | Short unique ID (compact, URL-safe) | | NOW | Current timestamp | | AUTOINCREMENT | Auto-incrementing integer | | SQL | Custom SQL expression | | Static | Any constant value ("active", false, 0) |

// Default value examples
{
  "id": {"type": "UUID", "defaultValue": {"type": "UUIDV4"}},
  "shortCode": {"type": "SUID", "defaultValue": {"type": "SUID"}},
  "createdAt": {"type": "DateTime", "defaultValue": {"type": "NOW"}},
  "orderNum": {"type": "Integer", "defaultValue": {"type": "AUTOINCREMENT"}},
  "sortOrder": {"type": "Integer", "defaultValue": {"type": "SQL", "value": "(SELECT MAX(sort)+1 FROM items)"}},
  "status": {"type": "String", "defaultValue": "pending"},
  "isActive": {"type": "Boolean", "defaultValue": true}
}

Supported Field Types

• String: values: {length: 255} for VARCHAR
• Text: Unlimited length text
• Integer, BigInt: Whole numbers
• Decimal: values: {precision: 10, scale: 2}
• Float, Real, Double: Floating point
• Boolean: true/false
• Date, DateTime, Time: Date/time values
• UUID: defaultValue: {type: "UUIDV4"}
• SUID: defaultValue: {type: "SUID"} - Short unique ID
• JSONB: JSON with indexing
• Array: values: {type: "String|Integer|etc"}
• Geometry, Geography: PostGIS spatial types
• Enum: values: {values: ["A", "B", "C"]}

Relationship Types

When using baasix_create_relationship:

// Many-to-One (products.category_Id → categories.id)
{
  sourceCollection: "products",
  relationshipData: {
    type: "M2O",
    name: "category",      // Creates category_Id field
    target: "categories",
    alias: "products"      // Reverse relation name
  }
}

// Many-to-Many (products ↔ tags)
// Auto-generates junction table: products_tags_tags_junction
{
  sourceCollection: "products",
  relationshipData: {
    type: "M2M",
    name: "tags",
    target: "tags",
    alias: "products"
  }
}

// Many-to-Many with custom junction table name
// Useful when auto-generated name exceeds PostgreSQL's 63 char limit
{
  sourceCollection: "products",
  relationshipData: {
    type: "M2M",
    name: "tags",
    target: "tags",
    alias: "products",
    through: "product_tags"  // Custom junction table name (max 63 chars)
  }
}

// Many-to-Any (polymorphic - comments can belong to posts OR products)
{
  sourceCollection: "comments",
  relationshipData: {
    type: "M2A",
    name: "commentable",
    tables: ["posts", "products"],
    alias: "comments",
    through: "comment_refs"  // Optional custom junction table name
  }
}

Junction Tables (M2M/M2A)

• Auto-generated name: {source}_{target}_{name}_junction
• Custom name: Use through property (max 63 characters for PostgreSQL)
• Schema property: Junction tables have isJunction: true in their schema definition
• Auto-indexed: Foreign key columns are automatically indexed for better query performance

Permission Structure

When using baasix_create_permission:

{
  role_Id: "uuid-of-role",
  collection: "products",
  action: "read",                    // read, create, update, delete
  fields: ["*"],                     // Or specific: ["name", "price"]
  conditions: {                      // Row-level security
    "published": {"eq": true}
  },
  relConditions: {                   // Filter related data
    "reviews": {"approved": {"eq": true}}
  }
}

Package Usage

Installation

npm install @tspvivek/baasix-mcp-server

Usage

import { startMCPServer } from '@tspvivek/baasix-mcp-server';

startMCPServer().catch((error) => {
  console.error('Failed to start MCP server:', error);
  process.exit(1);
});

Custom Server Instance

import { BaasixMCPServer } from '@tspvivek/baasix-mcp-server';

const server = new BaasixMCPServer();
server.run().catch(console.error);

Claude Code CLI Commands

# Add MCP server
claude mcp add baasix npm run start

# Remove MCP server
claude mcp remove baasix

File Structure

mcp/
├── server.js              # Entry point
├── package.json           # Dependencies and scripts
├── .env                   # Development config
├── .env.example           # Template
├── .env.production        # Production config
├── README.md              # This file
└── baasix/
    ├── index.js           # MCP server implementation
    └── config.js          # Configuration management

Requirements

• Node.js 18+
• Baasix server running (v0.1.0-alpha.2+)
• PostgreSQL 14+ (with PostGIS for geospatial)

Links

• Baasix Website: https://baasix.dev
• Documentation: https://baasix.dev/docs
• GitHub: https://github.com/tspvivek/baasix
• npm Package: https://www.npmjs.com/package/@tspvivek/baasix

License

MIT