Datasette MCP
Provides read-only access to Datasette instances hosted on Heroku, allowing SQL query execution, full-text search, and schema exploration of Heroku-hosted databases.
Connects to Datasette instances built with Python, enabling AI assistants to explore databases, execute SQL queries, and perform full-text searches against Python-based Datasette deployments.
Supports YAML-formatted configuration files for defining multiple Datasette instances, their connection details, and global server settings.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Datasette MCPshow me the schema for the users table in my production database"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Datasette MCP
⚠️ ALPHA SOFTWARE WARNING
This implementation is in early alpha and should NOT be used for production environments. MCP servers have serious potential safety issues that must be considered when accessing unvetted data. Use at your own risk.
A Model Context Protocol (MCP) server that provides read-only access to Datasette instances. This server enables AI assistants to explore, query, and analyze data from Datasette databases through a standardized interface.
Features
SQL Query Execution: Run custom SQL queries against Datasette databases
Full-Text Search: Search within tables using Datasette's FTS capabilities
Schema Exploration: List databases, tables, and inspect table schemas
Multiple Instances: Connect to multiple Datasette instances simultaneously
Authentication: Support for Bearer token authentication
Request Throttling: Configurable courtesy delays between requests
Multiple Transports: stdio, HTTP, and Server-Sent Events support
Related MCP server: SQLite MCP Server
Installation
Prerequisites
Python 3.10+
uv package manager
Install as a tool
# Install directly from GitHub
uv tool install git+https://github.com/mhalle/datasette-mcp.git
# Check installation
datasette-mcp --helpRun without installation
# Run directly with uvx (no installation required)
uvx git+https://github.com/mhalle/datasette-mcp.git --url https://your-datasette.com
# Or with config file
uvx git+https://github.com/mhalle/datasette-mcp.git --config /path/to/config.yamlDevelopment installation
# Clone and install for development
git clone https://github.com/mhalle/datasette-mcp.git
cd datasette-mcp
uv sync
uv run datasette-mcp --helpConfiguration
The server supports two configuration methods:
1. Configuration File
Create a YAML or JSON configuration file with your Datasette instances:
# ~/.config/datasette-mcp/config.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 requestsThe server automatically searches for config files in:
$DATASETTE_MCP_CONFIGenvironment variable~/.config/datasette-mcp/config.{yaml,yml,json}/etc/datasette-mcp/config.{yaml,yml,json}
2. Command Line (Single Instance)
For quick single-instance setup:
datasette-mcp \
--url https://my-datasette.herokuapp.com \
--id my_db \
--description "My database"Usage
Basic Startup
# Use auto-discovered config file
datasette-mcp
# Use specific config file
datasette-mcp --config /path/to/config.yaml
# Single instance mode
datasette-mcp --url https://example.com --id mydbTransport Options
# stdio (default, for MCP clients)
datasette-mcp
# HTTP server
datasette-mcp --transport streamable-http --port 8080
# Server-Sent Events
datasette-mcp --transport sse --host 0.0.0.0 --port 8080Development Usage
When developing or testing:
# Run from source with uv
uv run datasette-mcp --url https://example.com
# Install in development mode
uv tool install --editable .All CLI Options
--config CONFIG Path to configuration file
--url URL Datasette instance URL for single instance mode
--id ID Instance ID (optional, derived from URL if not specified)
--description DESC Description for the instance
--courtesy-delay FLOAT Delay between requests in seconds
--transport TRANSPORT Protocol: stdio, streamable-http, sse
--host HOST Host for HTTP transports (default: 127.0.0.1)
--port PORT Port for HTTP transports (default: 8198)
--log-level LEVEL Logging level: DEBUG, INFO, WARNING, ERRORClaude Code Integration
To use this MCP server with Claude Code:
1. Install the server
uv tool install git+https://github.com/mhalle/datasette-mcp.git2. Add to Claude Code
claude mcp add datasette-mcp -- datasette-mcp --url https://your-datasette-instance.comOr with a configuration file:
claude mcp add datasette-mcp -- datasette-mcp --config /path/to/config.yaml3. Use with scopes (optional)
claude mcp add -s data-analysis datasette-mcp -- datasette-mcp --url https://analytics.example.comOnce added, Claude Code will have access to explore and query your Datasette instances directly within conversations.
Available Tools
The server provides these MCP tools for AI assistants:
list_instances()
List all configured Datasette instances and their details.
list_databases(instance)
List all databases in a Datasette instance with table counts.
describe_database(instance, database)
Get complete database schema including all table structures, columns, types, and relationships in one efficient call.
execute_sql(instance, database, sql, ...)
Execute custom SQL queries with options for:
shape: Response format ("objects", "arrays", "array")json_columns: Parse specific columns as JSONtrace: Include performance trace informationtimelimit: Query timeout in millisecondssize: Maximum number of results per pagenext_token: Pagination token for getting next page
search_table(instance, database, table, search_term, ...)
Perform full-text search within a table with options for:
search_column: Search only in specific columncolumns: Return only specific columns to reduce tokensraw_mode: Enable advanced FTS operators (AND, OR, NOT)size: Maximum number of results per pagenext_token: Pagination token for getting next page
Usage Examples
Exploring Data Structure
# Step 1: See what Datasette instances are available
list_instances()
# Step 2: Explore databases in your chosen instance
list_databases(instance="my_database")
# Step 3: Get complete database schema with all tables and columns
describe_database(instance="my_database", database="main")Querying Data
# Get recent users with SQL
execute_sql(
instance="my_database",
database="main",
sql="SELECT * FROM users ORDER BY created_date DESC LIMIT 10"
)
# Search for specific content with limited columns to reduce tokens
search_table(
instance="my_database",
database="main",
table="posts",
search_term="machine learning",
columns=["title", "content", "author"],
size=20
)Advanced Queries
# Complex aggregation with pagination for large result sets
execute_sql(
instance="my_database",
database="main",
sql="SELECT category, COUNT(*) as count, AVG(price) as avg_price FROM products WHERE created_date > '2024-01-01' GROUP BY category ORDER BY count DESC",
size=50
)
# Search with advanced FTS operators
search_table(
instance="my_database",
database="main",
table="articles",
search_term="python AND (fastapi OR django)",
raw_mode=true
)Security Considerations
The server provides read-only access to Datasette instances
Authentication tokens are passed as Bearer tokens to Datasette
No write operations are supported
SQL queries are subject to Datasette's built-in security restrictions
Request throttling helps prevent overwhelming target servers
Error Handling
The server provides detailed error messages for:
Invalid SQL queries
Missing or inaccessible databases/tables
Authentication failures
Network timeouts
Configuration errors
Logging
Configure logging levels for debugging:
datasette-mcp --log-level DEBUGLog levels: DEBUG, INFO, WARNING, ERROR
Tool Management
# List installed tools
uv tool list
# Upgrade to latest version
uv tool upgrade datasette-mcp
# Uninstall
uv tool uninstall datasette-mcpContributing
This server is built with FastMCP, making it easy to extend with additional tools and functionality. The codebase follows MCP best practices for server development.
License
Licensed under the Apache License, Version 2.0. See LICENSE for details.
Related Projects
Datasette - Data exploration tool
FastMCP - Python MCP framework
Model Context Protocol - Standard for AI tool integration
Available Tools
5 toolsdescribe_databaseA
Get complete database metadata including all table schemas and column information.
| Name | Required | Description | Default |
|---|---|---|---|
| instance | Yes | Name of the Datasette instance (from config) | |
| database | Yes | Database name |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It only states a read operation but omits permissions, rate limits, or performance implications (e.g., potentially heavy schema retrieval).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence that front-loads the purpose and scope. No filler or redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low complexity, output schema present, and full parameter coverage, the description is largely sufficient. It would benefit from mentioning that it returns all schemas for the database, but it's already adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (instance and database have descriptions). The description does not add new parameter meaning beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it retrieves complete database metadata including table schemas and column information. It distinguishes from sibling tools like execute_sql (executes queries) and list_databases (lists databases).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when/when-not guidance is provided. The context of sibling tools implies usage but the description does not help choose between describe_database and search_table for column-level details.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
execute_sqlC
Execute SQL query against a Datasette instance.
| Name | Required | Description | Default |
|---|---|---|---|
| instance | Yes | Name of the Datasette instance (from config) | |
| database | Yes | Database name | |
| sql | Yes | SQL query to execute | |
| shape | No | JSON shape - "arrays", "objects", or "array" (uses Datasette default if not specified) | |
| json_columns | No | List of columns to parse as JSON | |
| trace | No | Include query performance trace | |
| timelimit | No | Query timeout in milliseconds | |
| size | No | Maximum number of results per page (uses Datasette default if not specified) | |
| next_token | No | Pagination token from previous response to get next page |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must fully disclose behavioral traits. However, it omits critical details such as whether the query is read-only or can mutate data, permission requirements, or error behavior, leaving the agent unaware of potential side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise (8 words) but at the cost of crucial information. It lacks any structure to convey important context, making it under-specified rather than efficiently concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (9 parameters, SQL execution), the absence of annotations, and the fact that an output schema exists but is not referenced, the description fails to provide adequate context about return format, pagination, or behavior, leaving significant gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds no additional meaning beyond the schema's parameter descriptions, but does not detract either.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Execute' and the resource 'SQL query against a Datasette instance', accurately capturing the tool's function. It effectively distinguishes from siblings like describe_database and search_table which have different purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like search_table. There is no mention of safety considerations (e.g., whether SQL can modify data) or prerequisites, leaving the AI agent without decision-making context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_databasesB
List all databases in a Datasette instance.
| Name | Required | Description | Default |
|---|---|---|---|
| instance | Yes | Name of the Datasette instance (from config) |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavior. It only states the action without confirming it's read-only, safe, or idempotent. It does not mention whether authentication is needed, rate limits, or any side effects. This leaves an agent uncertain about safety and constraints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, complete sentence that efficiently conveys the tool's purpose. It is front-loaded and contains no unnecessary words, earning its place as a concise and well-structured definition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has a simple function (list databases) and an output schema (existence noted in context), so the description minimally covers functionality. However, it lacks behavioral context such as read-only guarantee, pagination, or error conditions. With no annotations, the description should provide more completeness to fully inform the agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (the single parameter 'instance' has a clear schema description: 'Name of the Datasette instance (from config)'). The tool description adds no extra meaning beyond the schema, merely restating the instance context. With full coverage, the baseline is 3, and no additional value is provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'List all databases in a Datasette instance' clearly states the action (list), the resource (databases), and the scope (a specific instance). It effectively distinguishes from sibling tools like describe_database (specific db), execute_sql (queries), list_instances (instances), and search_table (searches table) by focusing on listing all databases.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus its siblings. It does not mention prerequisites, limitations, or context such as 'use this before describe_database to discover available databases'. Without such context, an AI agent may not understand the best scenario for invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_instancesA
List all configured Datasette instances.
Returns: List of instances with their configuration details
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description accurately indicates a read-only listing operation. It states it returns configuration details, which implies no side effects. However, it does not explicitly declare safety (e.g., read-only), but the behavioral intent is clear.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with two sentences, front-loading the core action. Every word is essential, with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter listing tool with an output schema present, the description is complete. It covers purpose and return value sufficiently.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has no parameters and schema coverage is 100%. The description adds no parameter details, but none are needed. Baseline for 0 params is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists all configured Datasette instances. The verb 'list' and resource 'Datasette instances' are specific, and the tool differentiates well from siblings that deal with databases or SQL.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like describe_database or list_databases. It simply states what it does, leaving the agent to infer usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
search_tableC
Full-text search within a table using Datasette's search functionality.
| Name | Required | Description | Default |
|---|---|---|---|
| instance | Yes | Name of the Datasette instance (from config) | |
| database | Yes | Database name | |
| table | Yes | Table name | |
| search_term | Yes | Text to search for | |
| search_column | No | Search only in this column (optional) | |
| columns | No | List of columns to return (optional, returns all columns if not specified) | |
| raw_mode | No | Enable advanced FTS operators (AND, OR, NOT, NEAR) | |
| shape | No | JSON shape - "arrays", "objects", or "array" (uses Datasette default if not specified) | |
| size | No | Maximum number of results (uses Datasette default if not specified) | |
| json_columns | No | List of columns to parse as JSON | |
| next_token | No | Pagination token from previous response to get next page |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden for behavioral disclosure. It only states 'full-text search' without clarifying whether the operation is read-only, if it requires authentication, or any side effects like logging. The mention of 'Datasette's search functionality' is vague and assumes prior knowledge.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that immediately states the core action ('search') and the target resource ('table'). It is front-loaded and contains no extraneous words, achieving maximum conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 11 parameters, including pagination (next_token) and optional column filters, the description is too brief. It does not explain how the tool handles pagination, the output shape, or the behavior of parameters like 'raw_mode'. An output schema exists but is not referenced, leaving the agent underinformed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All parameters have descriptions in the schema (100% coverage), so the description does not need to add much. It adds no parameter-specific meaning beyond what the schema already provides, earning the baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool performs 'full-text search within a table' using Datasette's search functionality. However, it does not differentiate from sibling tools like 'execute_sql' which could also perform searches, leaving ambiguity about when to use this specific tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. For instance, it does not explain when to prefer search_table over execute_sql for searching, or mention any prerequisites or constraints.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
5 tool updates
v0.8.1- First observed
describe_database - First observed
execute_sql - First observed
list_databases - First observed
list_instances - First observed
search_table
TDQS
Scored across 5 tools
Each tool has a clearly distinct purpose: describing a database, executing SQL, listing databases, listing instances, and searching a table. There is no functional overlap.
All tool names follow a consistent verb_noun pattern in snake_case (describe_database, execute_sql, list_databases, list_instances, search_table).
With 5 tools, the server is well-scoped for interacting with a Datasette instance, covering metadata retrieval, SQL execution, and full-text search without unnecessary complexity.
The tool surface covers all core operations expected for a Datasette instance: listing instances and databases, describing schemas, executing arbitrary SQL, and performing full-text search. No obvious gaps for the intended use case.
Maintenance
Related MCP Connectors
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
Draxlr's remote MCP server connects AI assistants to your SQL databases and dashboards. Explore schemas, run read-only queries, manage saved queries and dashboards, and export results, all with row-level security so each user sees only their own data.
A Model Context Protocol server for Wix AI tools
The Cortex MCP server provides read-only access to real-time engineering context from the Cortex developer portal, allowing AI coding assistants to answer natural language questions about your organization's catalog (microservices, libraries, domains, teams, infrastructure), scorecards (engineering standards and best practices), initiatives (goals and deadlines), and Engineering Intelligence metrics. It includes tools for querying documentation, tracking personal entities, and accessing AI-assisted insights across the entire Cortex ecosystem.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceA Model Context Protocol server that enables AI assistants to explore and interact with Cursor IDE's SQLite databases, providing access to project data, chat history, and composer information.24-
- AlicenseNot gradedqualityDmaintenanceA Model Context Protocol server implementation that enables AI assistants to execute SQL queries and interact with SQLite databases through a structured interface.7MIT
- AlicenseNot gradedqualityDmaintenanceA Model Context Protocol server implementation that connects AI assistants to DuckDB, enabling them to query and analyze data from various sources including CSV, Parquet, JSON, and cloud storage through SQL.18MIT
- AlicenseBqualityCmaintenanceA Model Context Protocol (MCP) server that provides read-only TDengine database queries for AI assistants, allowing users to execute queries, explore database structures, and investigate data directly from AI-powered tools.611MIT