mudbase-mcp-server

An MCP (Model Context Protocol) server that exposes Mudbase's database, storage, and search capabilities as tools for Claude Code, Claude Desktop, and any other MCP client.

Every request is authenticated with a Mudbase API key, so this connects your assistant directly to real data in your own Mudbase project: list and query collections, read and write documents, search across a project, and manage files in storage.

Requirements

• A Mudbase account and project. If you don't have one yet, create one at www.mudbase.dev.
• An API key for that project, generated from your project's API Keys settings.
• Node.js 18 or newer (only needed to run npx; most MCP clients already bundle Node).

Install

No install step is required. Point your MCP client at npx mudbase-mcp-server and it will download and run the latest version on demand.

Claude Code

Add this to your Claude Code MCP configuration:

{
  "mcpServers": {
    "mudbase": {
      "command": "npx",
      "args": ["mudbase-mcp-server"],
      "env": { "MUDBASE_API_KEY": "ak_..." }
    }
  }
}

Replace ak_... with a real API key from your Mudbase project settings. Restart Claude Code (or reload MCP servers) and the mudbase_* tools become available.

Other MCP clients

Any client that can launch an MCP server over stdio works the same way: run npx mudbase-mcp-server as the command, with MUDBASE_API_KEY set in its environment. Consult your client's own docs for where to put the command / args / env fields; the shape above is the common one.

Configuration

| Environment variable | Required | Description | | --- | --- | --- | | MUDBASE_API_KEY | Yes | Your Mudbase project API key. The server refuses to start without it and prints a clear error explaining how to set it. | | MUDBASE_BASE_URL | No | Override the API base URL (defaults to https://api.mudbase.dev). Only needed for a self-hosted or non-default deployment. |

The API key is read from the environment only. It is never logged, never written to disk, and never hardcoded anywhere in this package.

Available tools

Collections (read-only schema access)

• mudbase_list_collections: list every collection in a project, with each field's declared type.
• mudbase_get_collection: get one collection's full field schema and permission settings.

Documents (collection data)

• mudbase_list_documents: list documents in a collection, with pagination, sorting, and a JSON filter.
• mudbase_get_document: fetch a single document by ID.
• mudbase_create_document: create a new document.
• mudbase_update_document: partially update an existing document.
• mudbase_delete_document: permanently delete a document.

Search

• mudbase_search_documents: full-text search across a project, optionally scoped to specific collections or fields.

Storage

• mudbase_list_buckets: list the storage buckets in a project.
• mudbase_list_files: list files in a bucket, with search and MIME-type filters.
• mudbase_get_file: get metadata for a single stored file.
• mudbase_upload_file: upload a file from base64-encoded content.
• mudbase_delete_file: permanently delete a file.
• mudbase_get_file_download_url: generate a time-limited signed download URL for a file.

Every tool is a thin, typed wrapper over one real Mudbase API endpoint; none of them add new business logic beyond request shaping and error normalization. mudbase_delete_document and mudbase_delete_file are marked destructive in their tool metadata so a client can prompt for confirmation before calling them.

How errors are reported

A failed API call (invalid API key, missing project, validation error, rate limit, and so on) never crashes the server or throws an unhandled exception. It comes back to the MCP client as a normal tool result with isError: true and a JSON body describing what went wrong, for example:

{
  "error": "Mudbase rejected this API key. Check that MUDBASE_API_KEY is a valid, active key with access to this project.",
  "status": 401,
  "code": "unauthorized"
}

Development

npm install
npm run build       # compile TypeScript to dist/
npm run dev          # run the server directly from source with tsx
npm test              # run the unit test suite
npm run typecheck      # tsc --noEmit
npm run lint             # eslint

License

MIT. Built by the Mudbase Team.