Datasette

You run a MCP server that gives read-only access to Datasette instances, letting AI assistants explore, query, and analyze data through a standardized interface. It supports multiple Datasette sources, authentication, throttling, and several transport options to fit your workflow.

How to use

You can start and interact with the Datasette MCP server using an MCP client. Begin by configuring one or more Datasette instances you want to expose, then choose a transport method that matches your setup. You can explore available databases, list their schemas, run SQL queries, and perform full-text searches across your Datasette data. All actions respect the server’s read-only policy and are subject to the underlying Datasette security rules.

How to install

Prerequisites you need before installation are Python 3.10 or newer and the uv package manager.

Install as a tool from the source repository.

# Install directly from the repository
uv tool install git+https://github.com/mhalle/datasette-mcp.git

# Check installation
datasette-mcp --help

Run without a formal installation using a quick startup with uvx, which fetches and runs the MCP server from the repository and points it at your Datasette instance.

uvx git+https://github.com/mhalle/datasette-mcp.git --url https://your-datasette.com

# Or start with a config file
uvx git+https://github.com/mhelle/datasette-mcp.git --config /path/to/config.yaml

If you are actively developing, you can clone the project and run it from source, then install in development mode when ready.

# Clone and install for development
git clone https://github.com/mhalle/datasette-mcp.git
cd datasette-mcp
uv sync
uv run datasette-mcp --help

Additional configuration and options

Configuration supports two methods. You can use a configuration file to define Datasette instances or run a single instance directly from the command line.

# Example configuration (YAML)
datasette_instances:
  my_database:
    url: "https://my-datasette.herokuapp.com"
    description: "My production database"
    auth_token: "your-api-token-here"  # optional
  local_dev:
    url: "http://localhost:8001"
    description: "Local development database"

# Global settings (optional)
courtesy_delay_seconds: 0.5  # delay between requests

Or you can start a single instance directly with its URL and an identifier.

datasette-mcp \
  --url https://my-datasette.herokuapp.com \
  --id my_db \
  --description "My database"

Transport options include stdio (default), HTTP, or Server-Sent Events. You can customize host and port for HTTP-based transports.

# stdio (default, MCP client friendly)
datasette-mcp

# HTTP transport
datasette-mcp --transport streamable-http --port 8080

# Server-Sent Events
datasette-mcp --transport sse --host 0.0.0.0 --port 8080

Security, limits, and error handling

The server provides read-only access to Datasette instances and passes authentication tokens as Bearer tokens to Datasette. No write operations are supported. SQL queries are bounded by Datasette’s own security rules. A configurable courtesy delay between requests helps prevent overwhelming target servers.

If an error occurs, you receive detailed messages for issues like invalid SQL, missing databases, authentication failures, network timeouts, or configuration problems.

Usage with Claude Code (optional)

To integrate with Claude Code, install the MCP server, then add it to Claude Code so it can access your Datasette instances during conversations.

uv tool install git+https://github.com/mhalle/datasette-mcp.git

claude mcp add datasette-mcp -- datasette-mcp --url https://your-datasette-instance.com

Available tools

list_instances

Return a list of all configured Datasette instances with details such as URL and description.

list_databases

List every database available in a given Datasette instance along with table counts.

describe_database

Fetch the complete schema for a specified database, including tables, columns, and relationships.

execute_sql

Execute a SQL query against a specific database with options for result shape, JSON parsing, time limits, and pagination.

search_table

Perform a full-text search on a table with optional column scope, selected output columns, and pagination.