🚀 Xano Developer MCP

Supercharge your AI with the power of Xano

🤖 AI-Powered · 📚 Comprehensive Docs · ⚡ Instant Setup · 🔧 Built-in Tools

An MCP server and standalone library that gives AI assistants superpowers for developing on Xano — complete with documentation, code validation, and workflow guides. Use it as an MCP server or import the tools directly in your own applications.

💡 What's Xano? The fastest way to build a scalable backend for your app — no code required. Build APIs, manage databases, and deploy instantly.

🔗 Quick Links

| 🌐 Website | 📖 Docs | 📝 Blog | 💬 Community | 📦 npm | |:---:|:---:|:---:|:---:|:---:|

Overview

This MCP server acts as a bridge between AI models and Xano's developer ecosystem, offering:

• Meta API Documentation - Programmatically manage Xano workspaces, databases, APIs, functions, and more
• CLI Documentation - Command-line interface for local development, code sync, and execution
• XanoScript Documentation - Language reference with context-aware docs based on file type
• Code Validation - Syntax checking with the official XanoScript language server
• Workflow Guides - Step-by-step guides for common development tasks

Quick Start

Claude Code (Recommended)

claude mcp add xano -- npx -y @xano/developer-mcp

That's it! The MCP server will be automatically installed and configured.

Install via npm

You can also install the package globally from npm:

npm install -g @xano/developer-mcp

Then add to Claude Code:

claude mcp add xano-developer -- xano-developer-mcp

Claude Desktop

Add to your Claude Desktop configuration file:

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

{
  "mcpServers": {
    "xano-developer": {
      "command": "npx",
      "args": ["-y", "@xano/developer-mcp"]
    }
  }
}

Checking Your Version

npx @xano/developer-mcp --version

If installed from source:

node dist/index.js --version

Installation from Source

Prerequisites

• Node.js (ES2022+ compatible)
• npm

Setup

# Clone the repository
git clone https://github.com/xano-inc/xano-developer-mcp.git
cd xano-developer-mcp

# Install dependencies
npm install

# Build the project
npm run build

Usage

Running the Server

# Production
npm start

# Development (build + run)
npm run dev

The server communicates via stdio (standard input/output) using the JSON-RPC protocol, which is the standard transport for MCP servers.

Source Install Configuration

If you installed from source, configure your MCP client to use the local build:

Claude Code:

claude mcp add xano-developer node /path/to/xano-developer-mcp/dist/index.js

Claude Desktop:

{
  "mcpServers": {
    "xano-developer": {
      "command": "node",
      "args": ["/path/to/xano-developer-mcp/dist/index.js"]
    }
  }
}

Library Usage

In addition to using this package as an MCP server, you can import and use the tools directly in your own applications.

Installation

npm install @xano/developer-mcp

Importing Tools

import {
  validateXanoscript,
  xanoscriptDocs,
  metaApiDocs,
  cliDocs,
  mcpVersion
} from '@xano/developer-mcp';

Validate XanoScript Code

import { validateXanoscript } from '@xano/developer-mcp';

// Validate code directly
const result = validateXanoscript({ code: 'var:result = 1 + 2' });

if (result.valid) {
  console.log('Code is valid!');
} else {
  console.log('Validation errors:');
  result.errors.forEach(error => {
    console.log(`  Line ${error.range.start.line + 1}: ${error.message}`);
  });
}

// Validate a file
const fileResult = validateXanoscript({ file_path: './function/utils.xs' });

// Batch validate a directory
const dirResult = validateXanoscript({ directory: './api', pattern: '**/*.xs' });
console.log(`${dirResult.valid_files}/${dirResult.total_files} files valid`);

Get XanoScript Documentation

import { xanoscriptDocs } from '@xano/developer-mcp';

// Get overview (README)
const overview = xanoscriptDocs();
console.log(overview.documentation);

// Get specific topic
const syntaxDocs = xanoscriptDocs({ topic: 'syntax' });

// Get context-aware docs for a file path
const apiDocs = xanoscriptDocs({ file_path: 'api/users/create_post.xs' });

// Get compact quick reference
const quickRef = xanoscriptDocs({ topic: 'database', mode: 'quick_reference' });

// Get topic index with sizes
const index = xanoscriptDocs({ mode: 'index' });

Get Meta API Documentation

import { metaApiDocs } from '@xano/developer-mcp';

// Get overview
const overview = metaApiDocs({ topic: 'start' });

// Get detailed documentation with examples
const workspaceDocs = metaApiDocs({
  topic: 'workspace',
  detail_level: 'examples',
  include_schemas: true
});

console.log(workspaceDocs.documentation);

Get CLI Documentation

import { cliDocs } from '@xano/developer-mcp';

const cliSetup = cliDocs({ topic: 'start' });
console.log(cliSetup.documentation);

Get Package Version

import { mcpVersion } from '@xano/developer-mcp';

const { version } = mcpVersion();
console.log(`Using version ${version}`);

Available Exports

| Export | Description | |--------|-------------| | validateXanoscript | Validate XanoScript code and get detailed error information | | xanoscriptDocs | Get XanoScript language documentation | | metaApiDocs | Get Meta API documentation | | cliDocs | Get CLI documentation | | mcpVersion | Get the package version | | toolDefinitions | MCP tool definitions (for building custom MCP servers) | | handleTool | Tool dispatcher function (for building custom MCP servers) |

TypeScript Support

Full TypeScript support with exported types:

import type {
  ValidateXanoscriptArgs,
  ValidationResult,
  ParserDiagnostic,
  XanoscriptDocsArgs,
  MetaApiDocsArgs,
  CliDocsArgs,
  ToolResult
} from '@xano/developer-mcp';

Package Entry Points

The package provides multiple entry points:

// Main library entry (recommended)
import { validateXanoscript } from '@xano/developer-mcp';

// Tools module directly
import { validateXanoscript } from '@xano/developer-mcp/tools';

// Server module (for extending the MCP server)
import '@xano/developer-mcp/server';

Available Tools

1. validate_xanoscript

Validates XanoScript code for syntax errors. Supports multiple input methods. The language server auto-detects the object type from the code syntax.

Parameters: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | code | string | No | The XanoScript code to validate as a string | | file_path | string | No | Path to a single .xs file to validate | | file_paths | string[] | No | Array of file paths for batch validation | | directory | string | No | Directory path to validate all .xs files recursively | | pattern | string | No | Glob pattern to filter files when using directory (default: **/*.xs) |

One of code, file_path, file_paths, or directory is required.

Examples:

// Validate code directly
validate_xanoscript({ code: "var:result = 1 + 2" })

// Validate a single file
validate_xanoscript({ file_path: "function/utils/format.xs" })

// Validate multiple files
validate_xanoscript({ file_paths: ["api/users/get.xs", "api/users/create.xs"] })

// Validate all .xs files in a directory
validate_xanoscript({ directory: "api/users" })

// Validate with a specific pattern
validate_xanoscript({ directory: "src", pattern: "api/**/*.xs" })

Returns: List of errors with line/column positions and helpful suggestions, or confirmation of validity.

2. xanoscript_docs

Retrieves XanoScript programming language documentation with context-aware support.

Parameters: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | topic | string | No | Specific documentation topic to retrieve | | file_path | string | No | File path being edited for context-aware docs (e.g., api/users/create_post.xs) | | mode | string | No | full (default), quick_reference for compact syntax reference, or index for topic listing with sizes | | tier | string | No | Pre-packaged documentation tier for context-limited models: survival (~800 tokens) or working (~3500 tokens). Overrides topic/file_path/mode when set | | max_tokens | number | No | Maximum estimated token budget. Loads topics in priority order until budget is reached. Helps prevent context overflow for small-window models | | exclude_topics | string[] | No | Topic names to exclude from file_path results (e.g., topics already loaded) |

Available Topics:

| Topic | Description | |-------|-------------| | survival | Minimal syntax survival kit (~3KB, ~800 tokens) for models with <16K context | | working | Complete working reference (~12KB, ~3500 tokens) for models with 16-64K context | | readme | XanoScript overview, workspace structure, and quick reference | | essentials | Common patterns, quick reference, and common mistakes to avoid | | syntax | Expressions, operators, and filters for all XanoScript code | | syntax/string-filters | String filters, regex, encoding, security filters, text functions | | syntax/array-filters | Array filters, functional operations, and array functions | | syntax/functions | Math filters/functions, object functions, bitwise operations | | types | Data types, input blocks, and validation | | tables | Database schema definitions with indexes and relationships | | functions | Reusable function stacks with inputs and responses | | apis | HTTP endpoint definitions with authentication and CRUD patterns | | tasks | Scheduled and cron jobs | | triggers | Event-driven handlers (table, realtime, workspace, agent, MCP) | | database | All db.* operations: query, get, add, edit, patch, delete | | agents | AI agent configuration with LLM providers and tools | | tools | AI tools for agents and MCP servers | | mcp-servers | MCP server definitions exposing tools | | unit-testing | Unit tests, mocks, and assertions within functions, APIs, and middleware | | workflow-tests | End-to-end workflow tests with data sources and tags | | integrations | External service integrations index | | integrations/cloud-storage | AWS S3, Azure Blob, and GCP Storage | | integrations/search | Elasticsearch, OpenSearch, and Algolia | | integrations/redis | Redis caching, rate limiting, and queues | | integrations/external-apis | HTTP requests with api.request | | integrations/utilities | Local storage, email, zip, and Lambda | | frontend | Static frontend development and deployment | | run | Run job and service configurations | | addons | Reusable subqueries for fetching related data | | debugging | Logging, inspecting, and debugging XanoScript execution | | performance | Performance optimization best practices | | realtime | Real-time channels and events for push updates | | schema | Runtime schema parsing and validation | | security | Security best practices for authentication and authorization | | streaming | Streaming data from files, requests, and responses | | middleware | Request/response interceptors for functions, queries, tasks, and tools | | branch | Branch-level settings: middleware, history retention, visual styling | | workspace | Workspace-level settings: environment variables, preferences, realtime |

Examples:

// Get overview
xanoscript_docs()

// Get survival kit for small context models (~800 tokens)
xanoscript_docs({ tier: "survival" })

// Get working reference for medium context models (~3500 tokens)
xanoscript_docs({ tier: "working" })

// Get essentials (recommended first stop)
xanoscript_docs({ topic: "essentials" })

// Get specific topic
xanoscript_docs({ topic: "functions" })

// Discover available topics with sizes
xanoscript_docs({ mode: "index" })

// Budget-aware: load docs up to token limit
xanoscript_docs({ file_path: "api/users/create_post.xs", max_tokens: 2000 })

// Context-aware: get all docs relevant to file being edited
xanoscript_docs({ file_path: "api/users/create_post.xs" })

// Context-aware with exclusions (skip already-loaded topics)
xanoscript_docs({ file_path: "api/users/create_post.xs", exclude_topics: ["syntax", "essentials"] })

// Compact quick reference (uses less context)
xanoscript_docs({ topic: "database", mode: "quick_reference" })

3. mcp_version

Get the current version of the Xano Developer MCP server.

Parameters: None

Returns: The version string from package.json.

Example:

mcp_version()

4. meta_api_docs

Get documentation for Xano's Meta API. Use this to understand how to programmatically manage Xano workspaces, databases, APIs, functions, agents, and more.

Parameters: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | topic | string | Yes | Documentation topic to retrieve | | detail_level | string | No | overview, detailed (default), or examples | | include_schemas | boolean | No | Include JSON schemas for requests/responses (default: true) |

Available Topics:

| Topic | Description | |-------|-------------| | start | Getting started with the Meta API | | authentication | API authentication and authorization | | workspace | Workspace management endpoints | | apigroup | API group operations | | api | API endpoint management | | table | Database table operations | | function | Function management | | task | Scheduled task operations | | agent | AI agent configuration | | tool | AI tool management | | mcp_server | MCP server endpoints | | middleware | Middleware configuration | | branch | Branch management | | realtime | Real-time channel operations | | file | File management | | history | Version history | | workflows | Step-by-step workflow guides |

Examples:

// Get overview of Meta API
meta_api_docs({ topic: "start" })

// Get detailed table documentation
meta_api_docs({ topic: "table", detail_level: "detailed" })

// Get examples without schemas (smaller context)
meta_api_docs({ topic: "api", detail_level: "examples", include_schemas: false })

// Step-by-step workflow guides
meta_api_docs({ topic: "workflows" })

5. cli_docs

Get documentation for the Xano CLI. The CLI is optional but recommended for local development workflows. Not all users will have it installed.

• npm: https://www.npmjs.com/package/@xano/cli
• GitHub: https://github.com/xano-inc/cli

Use this tool to understand CLI commands for local development, code synchronization, and XanoScript execution.

Parameters: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | topic | string | Yes | Documentation topic to retrieve | | detail_level | string | No | overview, detailed (default), or examples |

Available Topics:

| Topic | Description | |-------|-------------| | start | Getting started with the CLI - installation and setup | | auth | Browser-based OAuth authentication | | profile | Profile management - credentials and multi-environment setup | | workspace | Workspace operations - pull/push code sync, git integration | | branch | Branch management - list, switch, create, and delete branches | | function | Function management - list, get, create, edit | | release | Release management - create, export, import, pull, push | | tenant | Tenant management - CRUD, deployments, env vars, backups, clusters | | unit_test | Unit test management - list and run unit tests | | workflow_test | Workflow test management - list, run, and manage workflow tests | | run | Run API commands - execute code, manage projects/sessions | | platform | Platform management - list and view platform versions | | static_host | Static hosting - deploy frontend builds | | update | Update the CLI to the latest version | | integration | CLI + Meta API integration guide - when to use each |

Examples:

// Get CLI setup guide
cli_docs({ topic: "start" })

// Learn when to use CLI vs Meta API
cli_docs({ topic: "integration" })

// Get workspace sync commands
cli_docs({ topic: "workspace", detail_level: "detailed" })

// Profile management with examples
cli_docs({ topic: "profile", detail_level: "examples" })

MCP Resources

The server also exposes XanoScript documentation as MCP resources for direct access:

| Resource URI | Description | |--------------|-------------| | xanoscript://docs/survival | Minimal syntax survival kit (~800 tokens) | | xanoscript://docs/working | Complete working reference (~3500 tokens) | | xanoscript://docs/readme | Overview and quick reference | | xanoscript://docs/essentials | Common patterns, quick reference, and common mistakes to avoid | | xanoscript://docs/syntax | Expressions, operators, and filters | | xanoscript://docs/syntax/string-filters | String filters, regex, encoding, security filters | | xanoscript://docs/syntax/array-filters | Array filters, functional operations | | xanoscript://docs/syntax/functions | Math filters/functions, object functions, bitwise | | xanoscript://docs/types | Data types and validation | | xanoscript://docs/tables | Database schema definitions | | xanoscript://docs/functions | Reusable function stacks | | xanoscript://docs/apis | HTTP endpoint definitions | | xanoscript://docs/tasks | Scheduled and cron jobs | | xanoscript://docs/triggers | Event-driven handlers | | xanoscript://docs/database | Database operations | | xanoscript://docs/agents | AI agent configuration | | xanoscript://docs/tools | AI tools for agents | | xanoscript://docs/mcp-servers | MCP server definitions | | xanoscript://docs/unit-testing | Unit tests and mocks | | xanoscript://docs/workflow-tests | End-to-end workflow tests | | xanoscript://docs/integrations | External service integrations index | | xanoscript://docs/integrations/cloud-storage | AWS S3, Azure Blob, GCP Storage | | xanoscript://docs/integrations/search | Elasticsearch, OpenSearch, Algolia | | xanoscript://docs/integrations/redis | Redis caching and queues | | xanoscript://docs/integrations/external-apis | HTTP requests with api.request | | xanoscript://docs/integrations/utilities | Email, zip, Lambda utilities | | xanoscript://docs/frontend | Static frontend development | | xanoscript://docs/run | Run job and service configurations | | xanoscript://docs/addons | Reusable subqueries for related data | | xanoscript://docs/debugging | Logging and debugging tools | | xanoscript://docs/performance | Performance optimization | | xanoscript://docs/realtime | Real-time channels and events | | xanoscript://docs/schema | Runtime schema parsing | | xanoscript://docs/security | Security best practices | | xanoscript://docs/streaming | Data streaming operations | | xanoscript://docs/middleware | Request/response interceptors | | xanoscript://docs/branch | Branch-level settings | | xanoscript://docs/workspace | Workspace-level settings |

npm Scripts

| Script | Command | Description | |--------|---------|-------------| | build | tsc && cp -r src/xanoscript_docs dist/ | Compile TypeScript and copy docs | | start | node dist/index.js | Run the MCP server | | dev | tsc && node dist/index.js | Build and run in development | | test | vitest run | Run unit tests | | test:watch | vitest | Run tests in watch mode | | test:coverage | vitest run --coverage | Run tests with coverage report |

Project Structure

xano-developer-mcp/
├── src/
│   ├── index.ts                        # MCP server entry point
│   ├── lib.ts                          # Library entry point (for npm imports)
│   ├── xanoscript.ts                   # XanoScript documentation logic
│   ├── xanoscript.test.ts              # Tests for xanoscript module
│   ├── xanoscript-language-server.d.ts # TypeScript declarations
│   ├── tools/                          # Standalone tool modules
│   │   ├── index.ts                    # Unified tool exports & handler
│   │   ├── index.test.ts               # Tests for tool handler
│   │   ├── types.ts                    # Common types (ToolResult)
│   │   ├── validate_xanoscript.ts      # XanoScript validation tool
│   │   ├── xanoscript_docs.ts          # XanoScript docs tool
│   │   ├── xanoscript_docs.test.ts     # Tests for xanoscript docs tool
│   │   ├── mcp_version.ts              # Version tool
│   │   ├── meta_api_docs.ts            # Meta API docs tool wrapper
│   │   └── cli_docs.ts                 # CLI docs tool wrapper
│   ├── meta_api_docs/                  # Meta API documentation
│   │   ├── index.ts                    # API docs handler
│   │   ├── index.test.ts               # Tests for index
│   │   ├── types.ts                    # Type definitions
│   │   ├── types.test.ts               # Tests for types
│   │   ├── format.ts                   # Documentation formatter
│   │   ├── format.test.ts              # Tests for formatter
│   │   └── topics/                     # Individual topic modules
│   ├── cli_docs/                       # Xano CLI documentation
│   │   ├── index.ts                    # CLI docs handler
│   │   ├── types.ts                    # Type definitions
│   │   ├── format.ts                   # Documentation formatter
│   │   └── topics/                     # Individual topic modules
│   └── xanoscript_docs/                # XanoScript language documentation
│       ├── docs_index.json             # Machine-readable topic registry
│       ├── version.json
│       ├── README.md
│       ├── essentials.md
│       ├── syntax.md
│       ├── syntax/                     # Syntax sub-topics
│       │   ├── string-filters.md
│       │   ├── array-filters.md
│       │   └── functions.md
│       └── ...
├── dist/                               # Compiled JavaScript output
├── vitest.config.ts                    # Test configuration
├── package.json
└── tsconfig.json

Dependencies

| Package | Version | Purpose | |---------|---------|---------| | @modelcontextprotocol/sdk | ^1.26.0 | Official MCP SDK | | @xano/xanoscript-language-server | ^11.6.5 | XanoScript parser and validation | | minimatch | ^10.1.2 | Glob pattern matching for context-aware docs |

Dev Dependencies

| Package | Version | Purpose | |---------|---------|---------| | typescript | ^5.9.0 | TypeScript compiler | | vitest | ^3.0.0 | Fast unit test framework | | @types/node | ^22.0.0 | Node.js type definitions | | @types/minimatch | ^5.1.2 | Minimatch type definitions |

How It Works

AI Client
    │
    ▼
MCP Protocol (JSON-RPC over stdio)
    │
    ▼
Xano Developer MCP Server
    │
    ├─► validate_xanoscript → Parses code with XanoScript language server
    │
    ├─► xanoscript_docs → Context-aware docs from /xanoscript_docs/*.md
    │
    ├─► meta_api_docs → Meta API documentation with detail levels
    │
    ├─► cli_docs → CLI documentation for local development workflows
    │
    ├─► mcp_version → Returns server version from package.json
    │
    └─► MCP Resources → Direct access to XanoScript documentation

Authentication

The MCP server and library functions do not require authentication. However, when using the documented APIs (Meta API) to interact with actual Xano services, you will need appropriate Xano API credentials. See the meta_api_docs tool for authentication details.

Development

Building

npm run build

Compiles TypeScript to JavaScript in the dist/ directory.

Documentation Structure

XanoScript Documentation (src/xanoscript_docs/):

• Markdown files for XanoScript language reference
• Configured in src/xanoscript_docs/docs_index.json with:
  • file: The markdown file containing the documentation
  • applyTo: Glob patterns for context-aware matching (e.g., api/**/*.xs)
  • description: Human-readable description of the topic
  • aliases: Alternative names for topic lookup
  • priority: Ordering weight for file_path matching

Meta API Documentation (src/meta_api_docs/):

• TypeScript modules with structured documentation
• Supports parameterized output (detail levels, schema inclusion)
• Better for AI consumption due to context efficiency

Testing

The project uses Vitest as its test framework with comprehensive unit tests.

Running Tests

# Run all tests
npm test

# Run tests in watch mode (re-runs on file changes)
npm run test:watch

# Run tests with coverage report
npm run test:coverage

Test Coverage

| Module | Test File | Description | |--------|-----------|-------------| | xanoscript.ts | xanoscript.test.ts | Core XanoScript documentation logic including file path matching and quick reference extraction | | tools/index.ts | tools/index.test.ts | Tool handler dispatch and argument validation | | tools/xanoscript_docs.ts | tools/xanoscript_docs.test.ts | XanoScript documentation tool and path resolution | | meta_api_docs/index.ts | meta_api_docs/index.test.ts | Meta API documentation handler and topic management | | meta_api_docs/format.ts | meta_api_docs/format.test.ts | Documentation formatting for endpoints, examples, and patterns | | meta_api_docs/types.ts | meta_api_docs/types.test.ts | Type structure validation |

Test Structure

Tests are co-located with source files using the .test.ts suffix:

src/
├── xanoscript.ts
├── xanoscript.test.ts          # Tests for xanoscript.ts
├── tools/
│   ├── index.ts
│   ├── index.test.ts           # Tests for tool handler
│   ├── xanoscript_docs.ts
│   ├── xanoscript_docs.test.ts # Tests for xanoscript docs tool
│   └── ...
├── meta_api_docs/
│   ├── index.ts
│   ├── index.test.ts           # Tests for index.ts
│   ├── format.ts
│   ├── format.test.ts          # Tests for format.ts
│   └── ...

Writing Tests

Tests use Vitest's API which is compatible with Jest:

import { describe, it, expect } from "vitest";
import { myFunction } from "./myModule.js";

describe("myFunction", () => {
  it("should return expected result", () => {
    expect(myFunction("input")).toBe("expected");
  });
});

License

See LICENSE for details.