rizrmd/clay-mcp

Clay MCP - Data Analysis Server

A Model Context Protocol (MCP) server for data analysis with real TypeScript execution, PostgreSQL connections, and Claude Code integration.

Features

• Auto-registration: Clients are automatically registered on first request
• Connection Management: CRUD operations for PostgreSQL connections per client
• TypeScript Analysis: Create and execute TypeScript analysis functions with real V8 runtime
• HTTP Transport: Native HTTP/SSE support for Claude Code integration
• Persistent Storage: SQLite database with Docker volume persistence
• Client Isolation: Each client has isolated connections and analyses

Quick Start

Prerequisites

• Docker
• Claude Code CLI (npm install -g @anthropic/claude-code)

Installation

1. Run the Docker container:

docker run -d \
  --name clay-mcp \
  -p 5865:5865 \
  -v clay-mcp-data:/data \
  -e DATABASE_URL=sqlite:/data/clay_mcp.db \
  -e MCP_TRANSPORT=http \
  -e MCP_PORT=5865 \
  -e RUST_LOG=info \
  --restart unless-stopped \
  ghcr.io/rizrmd/clay-mcp:latest

2. Add to Claude Code:

claude mcp add --transport http clay-mcp http://localhost:5865

3. Verify connection:

claude mcp list
# Output: clay-mcp: http://localhost:5865 (HTTP) - ✓ Connected

Usage

In Claude Code

Once configured, you can use Clay MCP directly in your Claude prompts:

Create a PostgreSQL connection named 'analytics_db' with connection string 'postgresql://user:pass@localhost:5432/analytics'

Create a TypeScript analysis named 'user_growth' that queries user registrations from the last 30 days

Execute the 'user_growth' analysis using the 'analytics_db' connection

Available Tools

Clay MCP provides 10 tools for data analysis:

Connection Management:

• create_connection - Add PostgreSQL connections
• update_connection - Modify existing connections
• delete_connection - Remove connections
• list_connections - View all connections for a client
• test_connection - Check connection health

Analysis Management:

• create_analysis - Write TypeScript analysis functions
• update_analysis - Modify analysis code
• delete_analysis - Remove analyses
• list_analyses - View all analyses for a client
• execute_analysis - Run analyses with real V8 execution

Example Analysis

// Create an analysis that queries multiple databases
async function main() {
  // Query users from primary database
  const users = await query("primary_db", 
    "SELECT id, name, created_at FROM users WHERE created_at > $1",
    [new Date(Date.now() - 30 * 24 * 60 * 60 * 1000)]
  );
  
  // Query orders from analytics database
  const orders = await query("analytics_db",
    "SELECT user_id, COUNT(*) as order_count FROM orders GROUP BY user_id"
  );
  
  // Combine and analyze data
  const analysis = users.map(user => {
    const userOrders = orders.find(o => o.user_id === user.id);
    return {
      ...user,
      order_count: userOrders?.order_count || 0
    };
  });
  
  return {
    total_users: users.length,
    users_with_orders: analysis.filter(u => u.order_count > 0).length,
    top_users: analysis.sort((a, b) => b.order_count - a.order_count).slice(0, 10)
  };
}

API Reference

HTTP Endpoints

• POST / - JSON-RPC endpoint for MCP protocol
• GET /sse - Server-Sent Events for real-time updates

Client Isolation

Each client is identified by a client_id that's automatically included in requests. Clients have isolated:

• Database connections
• Analysis functions
• Execution logs

Building from Source

Prerequisites

• Rust 1.75+
• Docker (optional)

Build locally:

git clone https://github.com/rizrmd/clay-mcp
cd clay-mcp
cargo build --release

Run locally:

DATABASE_URL=sqlite:clay_mcp.db \
MCP_TRANSPORT=http \
MCP_PORT=5865 \
RUST_LOG=info \
./target/release/clay-mcp

Build Docker image:

docker build -t clay-mcp:latest .

Configuration

Environment Variables

• DATABASE_URL - SQLite database path (default: sqlite:clay_mcp.db)
• MCP_TRANSPORT - Transport type: http or stdio (default: stdio)
• MCP_PORT - HTTP server port (default: 5865)
• RUST_LOG - Log level: debug, info, warn, error

Docker Volumes

• /data - Persistent storage for SQLite database

Management

Container Management

# View logs
docker logs clay-mcp -f

# Restart
docker restart clay-mcp

# Stop
docker stop clay-mcp

# Remove (keeps data)
docker rm clay-mcp

Data Backup

# Backup
docker run --rm -v clay-mcp-data:/data -v $(pwd):/backup \
  alpine tar czf /backup/clay-mcp-backup.tar.gz /data

# Restore
docker run --rm -v clay-mcp-data:/data -v $(pwd):/backup \
  alpine tar xzf /backup/clay-mcp-backup.tar.gz -C /

Claude Code Management

# List MCP servers
claude mcp list

# Get server details
claude mcp get clay-mcp

# Remove server
claude mcp remove clay-mcp

# Re-add server
claude mcp add --transport http clay-mcp http://localhost:5865

Technical Details

Architecture

• Runtime: Rust with Tokio async runtime
• JavaScript Engine: V8 via deno_core for TypeScript execution
• Database: SQLite for metadata, PostgreSQL for user data
• Protocol: MCP over HTTP with SSE support
• Transport: HTTP/JSON-RPC with proper protocol version negotiation

Security

• Client isolation via unique client_id
• Sandboxed TypeScript execution
• Connection strings stored securely
• No cross-client data access

Troubleshooting

Connection Issues

# Check if server is running
curl http://localhost:5865/ -X POST \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{}},"id":1}'

# Check Docker status
docker ps --filter name=clay-mcp

# View server logs
docker logs clay-mcp --tail 50

Common Issues

1. Port already in use: Change port with -e MCP_PORT=5866
2. Database locked: Restart container with docker restart clay-mcp
3. Connection failed: Ensure Docker is running and port 5865 is not blocked

License

MIT

Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.

Links

• GitHub Repository
• Model Context Protocol
• Claude Code