# 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)](https://modelcontextprotocol.io/) server that provides read-only access to [Datasette](https://datasette.io/) 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](https://docs.astral.sh/uv/) package manager

### Install as a tool

```bash
# Install directly from GitHub
uv tool install git+https://github.com/mhalle/datasette-mcp.git

# Check installation
datasette-mcp --help
```

### Run without installation

```bash
# 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

```bash
# 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:

```yaml
# ~/.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:
1. `$DATASETTE_MCP_CONFIG` environment variable
2. `~/.config/datasette-mcp/config.{yaml,yml,json}`
3. `/etc/datasette-mcp/config.{yaml,yml,json}`

### 2. Command Line (Single Instance)

For quick single-instance setup:

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

## Usage

### Basic Startup

```bash
# 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

```bash
# 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:

```bash
# 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](https://claude.ai/code):

### 1. Install the server

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

### 2. Add to Claude Code

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

Or with a configuration file:

```bash
claude mcp add datasette-mcp -- datasette-mcp --config /path/to/config.yaml
```

### 3. Use with scopes (optional)

```bash
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 JSON
- `trace`: Include performance trace information
- `timelimit`: Query timeout in milliseconds
- `size`: Maximum number of results per page
- `next_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 column
- `columns`: Return only specific columns to reduce tokens
- `raw_mode`: Enable advanced FTS operators (AND, OR, NOT)
- `size`: Maximum number of results per page
- `next_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:

```bash
datasette-mcp --log-level DEBUG
```

Log levels: `DEBUG`, `INFO`, `WARNING`, `ERROR`

### Tool Management

```bash
# 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](https://gofastmcp.com/), 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](LICENSE) for details.

## Related Projects

- [Datasette](https://datasette.io/) - Data exploration tool
- [FastMCP](https://gofastmcp.com/) - Python MCP framework
- [Model Context Protocol](https://modelcontextprotocol.io/) - Standard for AI tool integration