DataSF MCP Server

DataSF MCP Server

A Model Context Protocol (MCP) server that provides LLMs with seamless access to San Francisco's open data portal (DataSF), powered by the Socrata platform.

Overview

This MCP server enables AI assistants like Claude to search, explore, and query San Francisco's public datasets through a simple, standardized interface. It handles the complexity of the Socrata API, provides intelligent column name correction, and includes schema caching for optimal performance.

Key Features

• 🔍 Dataset Search & Discovery - Find datasets by keywords or browse by category
• 📊 Schema Retrieval - Get column names and data types before querying
• 💬 SoQL Query Execution - Run SQL-like queries against any dataset
• 🎯 Fuzzy Column Matching - Auto-corrects typos in column names
• ⚡ Schema Caching - Reduces API calls with intelligent caching
• 🔐 Optional Authentication - Supports Socrata App Tokens for higher rate limits
• ✅ Property-Based Testing - Comprehensive correctness guarantees

Available Tools

1. `search_datasf`

Search for datasets by keywords.

Parameters:

• query (string, required): Search keywords (1-500 characters)
• limit (number, optional): Max results (default: 5, max: 20)

Example:

Search for police incident datasets

2. `list_datasf`

Browse available datasets, optionally filtered by category.

Parameters:

• category (string, optional): Filter by category
• limit (number, optional): Max results (default: 5, max: 20)

Example:

List recent public safety datasets

3. `get_schema`

Get the schema (columns and data types) for a specific dataset.

Parameters:

• dataset_id (string, required): Dataset 4x4 ID (format: xxxx-xxxx)

Example:

Get the schema for dataset wg3w-h783

4. `query_datasf`

Execute a SoQL (Socrata Query Language) query against a dataset.

Parameters:

• dataset_id (string, required): Dataset 4x4 ID
• soql (string, required): SoQL query (1-4000 characters)
• auto_correct (boolean, optional): Enable column name correction (default: true)

Example:

Query dataset wg3w-h783: SELECT incident_category, COUNT(*) GROUP BY incident_category LIMIT 10

Installation

Prerequisites

• Node.js 18 or higher
• npm or yarn

Local Setup (Optional)

If you want to run or modify the server locally:

1. Clone the repository:

git clone https://github.com/fwextensions/datasf-mcp.git
cd datasf-mcp

2. Install dependencies:

npm install

3. Run the server:

npm start

The server uses tsx to run TypeScript directly without a build step.

Usage

Testing with MCP Inspector

For the MCP Inspector, you'll need to use the local installation:

# First, clone and install locally
git clone https://github.com/fwextensions/datasf-mcp.git
cd datasf-mcp
npm install

# Then run the inspector
npx -y @modelcontextprotocol/inspector tsx src/index.ts

In the inspector UI, use:

• Command: tsx
• Arguments: src/index.ts (or absolute path if running from outside the directory)

Quick Start with npx (Recommended)

The easiest way to use the server is directly from GitHub using npx:

{
  "mcpServers": {
    "datasf": {
      "command": "npx",
      "args": ["-y", "github:fwextensions/datasf-mcp"],
      "env": {
        "SOCRATA_APP_TOKEN": "your-optional-token"
      }
    }
  }
}

This will automatically download and run the latest version from GitHub without any manual installation.

Local Installation

Alternatively, clone and install locally:

git clone https://github.com/fwextensions/datasf-mcp.git
cd datasf-mcp
npm install

Then use the absolute path in your MCP configuration (see below).

Configuration for Claude Desktop

Add to your Claude Desktop config file:

Windows: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

Option 1: Using npx (recommended)

{
  "mcpServers": {
    "datasf": {
      "command": "npx",
      "args": ["-y", "github:fwextensions/datasf-mcp"],
      "env": {
        "SOCRATA_APP_TOKEN": "your-optional-token"
      }
    }
  }
}

Option 2: Using local installation

{
  "mcpServers": {
    "datasf": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/datasf-mcp/src/index.ts"],
      "env": {
        "SOCRATA_APP_TOKEN": "your-optional-token"
      }
    }
  }
}

Important: Replace /absolute/path/to/datasf-mcp with the actual full path to where you cloned this project.

Configuration for Kiro IDE

Create or edit .kiro/settings/mcp.json:

Option 1: Using npx from GitHub (recommended)

{
  "mcpServers": {
    "datasf": {
      "command": "npx",
      "args": ["-y", "github:fwextensions/datasf-mcp"],
      "env": {
        "SOCRATA_APP_TOKEN": "your-optio