quilt-mcp 0.8.0

Secure MCP server for accessing Quilt data with JWT authentication

Quilt MCP Server

MCP server for Quilt data catalog - search, analyze, and manage data packages with 84+ tools.

Quick Start

1. Terminal (Direct)

# Run directly with uvx (requires uv: https://docs.astral.sh/uv/)
uvx quilt-mcp

# Or install globally
uv tool install quilt-mcp
quilt-mcp

2. Claude Desktop (One-Click)

1. Download .mcpb from releases
2. Double-click to install or drag to Claude Desktop
3. Configure catalog in Settings → Extensions → Quilt MCP

3. Claude Code CLI

# Add to Claude Code CLI with environment variables
npx @anthropic-ai/claude-code mcp add quilt-mcp uvx quilt-mcp \
  -e QUILT_CATALOG_DOMAIN=your-catalog.quiltdata.com \
  -e AWS_PROFILE=your-profile

4. Custom MCP Clients

Add to your mcp.json:

{
  "mcpServers": {
    "quilt": {
      "command": "uvx",
      "args": ["quilt-mcp"],
      "env": {
        "QUILT_CATALOG_DOMAIN": "quilt-stack.yourcompany.com"
      }
    }
  }
}

🎓 Workshop Materials

Running a workshop or training session? We have complete workshop materials with AWS Bedrock integration:

📚 Workshop Guide →

Includes:

• Step-by-step participant guide - Installation, configuration, hands-on exercises
• Instructor guide - Timeline, talking points, troubleshooting
• Email templates - HubSpot-compatible templates for sending AWS credentials
• Quick reference cards - Common prompts and tool categories
• Pre-event checklist - What participants need to install beforehand

Perfect for:

• Team training sessions
• Conference workshops
• Educational courses
• Internal enablement

Configuration

Authentication

quilt-mcp supports dual-mode authentication at runtime:

• JWT (web deployments): When the HTTP transport provides a bearer token, the server verifies it and uses the JWT-derived AWS session for all tools.
• IAM/quilt3 (desktop & CLIs): Without a JWT, the server transparently falls back to the existing quilt3 login flow so local workflows keep working.

Configure or refresh quilt3 credentials with:

# Configure catalog and authenticate (interactive)
quilt3 config

# Or set directly
quilt3 config https://your-catalog.quiltdata.com

# Login (opens browser for SSO, or prompts for credentials)
quilt3 login

Your credentials are stored in ~/.quilt/ and automatically used by quilt-mcp whenever a JWT is not present.

To require JWTs in production deployments, set MCP_REQUIRE_JWT=true. In strict mode, bucket and package tools return a clear error instead of falling back to quilt3 credentials.

Environment Variables

Override defaults via environment or MCP config:

• QUILT_CATALOG_DOMAIN - Your Quilt catalog URL (e.g., your-catalog.quiltdata.com)
• QUILT_DEFAULT_BUCKET - Default S3 bucket (e.g., s3://your-bucket)
• AWS_PROFILE - AWS credentials profile for S3 access
• MCP_REQUIRE_JWT - Set to true to reject IAM/quilt3 fallback and enforce JWT-only access

Development

# Clone and setup
git clone https://github.com/quiltdata/quilt-mcp-server.git
cd quilt-mcp-server

# Install and run
uv sync
make run

# Test
make test

Documentation

• MCP Protocol
• Quilt Documentation
• API Reference
• Contributing

Troubleshooting

SyntaxWarning from jsonlines

You may see this warning during installation:

SyntaxWarning: invalid escape sequence '\*'

This is harmless. It's from the jsonlines dependency (via quilt3) and doesn't affect functionality. The warning appears on Python 3.12+ due to deprecated escape sequences in the library's docstrings.

Support

• GitHub Issues
• Quilt Support

License

Apache 2.0 - See LICENSE.txt