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
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 --help
Run 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.yaml
Development installation
# Clone and install for development
git clone https://github.com/mhalle/datasette-mcp.git
cd datasette-mcp
uv sync
uv run datasette-mcp --help
Configuration
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 requests
The 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 mydb
Transport 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 8080
Development 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, ERROR
Claude Code Integration
To use this MCP server with Claude Code:
1. Install the server
uv tool install git+https://github.com/mhalle/datasette-mcp.git
2. Add to Claude Code
claude mcp add datasette-mcp -- datasette-mcp --url https://your-datasette-instance.com
Or with a configuration file:
claude mcp add datasette-mcp -- datasette-mcp --config /path/to/config.yaml
3. Use with scopes (optional)
claude mcp add -s data-analysis datasette-mcp -- datasette-mcp --url https://analytics.example.com
Once 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 DEBUG
Log 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-mcp
Contributing
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