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"]
    }
  }
}

Xano Skills

This repo ships two agent skills under skills/:

• xano-init — guided setup that profiles a Xano workspace and builds a sandbox-first development playbook
• xanoscript-docs-expert — deep reference for working with XanoScript documentation and this MCP project's architecture

Using Claude Code inside this repo? You already have both skills. They're committed to .claude/skills/ and load automatically when Claude Code starts a session in this directory — no install step needed. Just invoke xano-init or xanoscript-docs-expert by name, or describe the task in natural language.

Using a different agent, or want the skills available in other projects? Skills are distributed via the open Agent Skills standard and install with a single npx command — no cloning or manual file copying.

Install xano-init globally into Claude Code:

npx skills add xano-inc/xano-developer-mcp -s xano-init -a claude-code -g

Install into multiple agents at once (Claude Code, Codex, Cursor, OpenCode, etc.):

npx skills add xano-inc/xano-developer-mcp -s xano-init \
  -a claude-code -a codex -a cursor -a opencode -g

Drop -s to install every skill in the repo, or drop -g to scope the install to the current project instead of your user profile. Other supported agents include gemini-cli, windsurf, continue, cline, github-copilot, and more — see the skills CLI for the full list.

Start a new agent session after installing so the skill manifest is picked up.

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
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
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
sandbox	Personal auto-provisioned dev environment (free-tier friendly)
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
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/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/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.