Research & Insights MCP Server

Supercharge Claude Desktop with bulk analysis of 1500+ user research calls, validation workflows, and Signal export capabilities.

A Model Context Protocol (MCP) server that connects Claude Desktop to your Supabase-backed research repository, enabling AI-powered analysis of customer calls, user interviews, and support conversations at scale.

🎯 What This Does

This MCP server gives Claude Desktop direct access to your user research database, enabling you to:

• 🔍 Search across 1500+ calls with natural language queries

• 📊 Aggregate insights by theme across multiple recordings

• ✅ Validate research findings with ML-powered confidence scoring

• 📈 Track trends over time (week-over-week, month-over-month)

• 🎯 Extract competitive intelligence from customer conversations

• 📦 Export to Signal for cross-functional sharing

Instead of manually reviewing hundreds of calls, ask Claude:

"What are the top 5 pain points mentioned in discovery calls this month?"

"Show me all feature requests from enterprise customers with high confidence scores"

"Which competitors are mentioned most frequently, and in what context?"

Claude can now answer these questions by directly querying your research database.

🚀 Quick Start

Prerequisites

• Node.js 18+ installed

• Claude Desktop (download here)

• Supabase project with research data (see Database Setup)

1. Install

git clone https://github.com/ecidk/mcp-research-insights.git
cd mcp-research-insights
npm install
npm run build

2. Configure Environment

Copy .env.example to .env:

cp .env.example .env

Edit .env with your credentials:

SUPABASE_URL=https://your-project.supabase.co
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key-here
NODE_ENV=production
LOG_LEVEL=info

3. Register with Claude Desktop

Add to ~/.claude/mcp.json (create if it doesn't exist):

{
  "mcpServers": {
    "research-insights": {
      "type": "stdio",
      "command": "node /absolute/path/to/mcp-research-insights/dist/index.js",
      "env": {
        "SUPABASE_URL": "https://your-project.supabase.co",
        "SUPABASE_SERVICE_ROLE_KEY": "${SUPABASE_SERVICE_ROLE_KEY}"
      }
    }
  }
}

💡 Tip: Use environment variable substitution (${SUPABASE_SERVICE_ROLE_KEY}) to avoid hardcoding secrets.

4. Restart Claude Desktop

The MCP server will auto-start when Claude Desktop launches. Look for the 🔌 indicator showing "research-insights" is connected.

💬 Example Conversations

Once connected, you can have conversations like:

You: "Search for all discovery calls from the last 30 days where customers mentioned pricing concerns"

Claude: Uses search_insights_by_scope with filters: call_type=discovery, date_range=last_30_days, sentiment=negative, keywords=pricing

You: "What are the most common feature requests from enterprise customers?"

Claude: Uses analyze_feature_requests filtered by customer segment, then aggregate_insights_by_theme to cluster similar requests

You: "Show me the validation queue and predict which insights are likely to be approved"

Claude: Calls get_validation_queue then predict_validation_outcome for each item, providing confidence scores

🛠️ 69 Available Tools

Major expansion in v2.0: Added 51 new tools across workflow automation, advanced analytics, customer journey mapping, integrations, AI research assistance, and quality/compliance features.

🔍 Search & Retrieval (7 tools)

📊 Analysis & Aggregation (5 tools)

✅ Validation Workflow (4 tools)

🔄 Workflow Automation (4 tools)

🚨 Proactive Alerts (2 tools)

📋 Stakeholder Reports (3 tools)

📈 Advanced Analytics (7 tools)

🗺️ Customer Journey (6 tools)

🔌 Integrations (4 tools)

🤖 AI Research Assistant (4 tools)

✅ Quality & Compliance (4 tools)

✅ Validation Workflow (4 tools)

📦 Signal Export (2 tools)

🗄️ Database Setup

This MCP server requires a Supabase project with the following tables:

Core Tables

-- UX analysis results
CREATE TABLE ux_analysis (
  id UUID PRIMARY KEY,
  recording_id UUID REFERENCES recordings(id),
  call_breakdown JSONB,
  question_analysis JSONB,
  next_steps JSONB,
  created_at TIMESTAMPTZ DEFAULT NOW()
);

-- Insight validations
CREATE TABLE ux_insight_validations (
  id UUID PRIMARY KEY,
  insight_id UUID,
  insight_type TEXT,
  validation_status TEXT, -- validated, needs_review, rejected
  confidence_score FLOAT,
  reason_codes TEXT[],
  validated_at TIMESTAMPTZ,
  created_at TIMESTAMPTZ DEFAULT NOW()
);

-- Collections (curated groups)
CREATE TABLE ux_collections (
  id UUID PRIMARY KEY,
  name TEXT,
  description TEXT,
  created_by UUID REFERENCES auth.users(id),
  created_at TIMESTAMPTZ DEFAULT NOW()
);

-- Collection items (many-to-many)
CREATE TABLE ux_collection_items (
  collection_id UUID REFERENCES ux_collections(id),
  insight_id UUID,
  added_at TIMESTAMPTZ DEFAULT NOW(),
  PRIMARY KEY (collection_id, insight_id)
);

-- Recordings metadata
CREATE TABLE recordings (
  id UUID PRIMARY KEY,
  title TEXT,
  duration INTEGER,
  created_at TIMESTAMPTZ DEFAULT NOW(),
  user_id UUID REFERENCES auth.users(id),
  content_type TEXT -- 'user_experience', 'sales_call', 'customer_support'
);

Required Views

-- Validation queue view
CREATE VIEW ux_validation_queue AS
SELECT 
  v.id,
  v.insight_id,
  v.insight_type,
  v.confidence_score,
  v.validation_status,
  v.created_at,
  a.call_breakdown->>'summary' AS insight_context
FROM ux_insight_validations v
LEFT JOIN ux_analysis a ON v.insight_id = a.recording_id
WHERE v.validation_status = 'needs_review'
ORDER BY v.confidence_score ASC, v.created_at ASC;

Optional: API Key Authentication

-- MCP API keys (hashed)
CREATE TABLE ux_mcp_api_keys (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  key_hash TEXT NOT NULL UNIQUE,
  user_id UUID REFERENCES auth.users(id),
  description TEXT,
  scopes TEXT[] DEFAULT ARRAY['read'],
  last_used_at TIMESTAMPTZ,
  created_at TIMESTAMPTZ DEFAULT NOW()
);

-- Rate limiting function
CREATE OR REPLACE FUNCTION check_mcp_rate_limit(
  p_key_hash TEXT,
  p_limit INTEGER DEFAULT 100
) RETURNS BOOLEAN AS $$
  -- Implementation: check if key_hash has exceeded p_limit requests in last minute
$$ LANGUAGE plpgsql;

💡 See DEPLOYMENT_GUIDE.md for full schema and migration scripts.

🔐 Security Best Practices

⚠️ Critical: Never Expose Your Service Role Key

The SUPABASE_SERVICE_ROLE_KEY bypasses Row Level Security (RLS) and grants full admin access to your database.

✅ Do This:

• ✅ Store in .env file (already in .gitignore)

• ✅ Use environment variables in production

• ✅ Rotate immediately if exposed

• ✅ Use separate keys for dev/staging/production

• ✅ Enable RLS on all tables (defense in depth)

• ✅ Monitor API usage for anomalies

❌ Never Do This:

• ❌ Commit .env to git

• ❌ Share keys in Slack, email, or screenshots

• ❌ Use production keys in development

• ❌ Hardcode keys in source code

• ❌ Expose keys in error messages or logs

Row Level Security (RLS)

Even with the service role key, enable RLS as a safety layer:

-- Example: Users can only access their own recordings
CREATE POLICY "Users access own recordings" 
ON recordings FOR SELECT 
USING (auth.uid() = user_id);

-- Admins can access all recordings
CREATE POLICY "Admins access all recordings"
ON recordings FOR SELECT
USING (
  EXISTS (
    SELECT 1 FROM user_roles 
    WHERE user_id = auth.uid() 
    AND role = 'admin'
  )
);

📖 Full security policy: SECURITY.md

🏗️ Architecture

┌─────────────────┐
│ Claude Desktop  │
└────────┬────────┘
         │ stdio (MCP)
         ↓
┌─────────────────────────────┐
│  Research & Insights MCP    │
│                             │
│  ┌─────────────────────┐   │
│  │  18 Tools           │   │
│  │  - Search           │   │
│  │  - Analysis         │   │
│  │  - Validation       │   │
│  │  - Export           │   │
│  └─────────────────────┘   │
│                             │
│  ┌─────────────────────┐   │
│  │  Authentication     │   │
│  │  - API key (SHA-256)│   │
│  │  - Rate limiting    │   │
│  └─────────────────────┘   │
└─────────┬───────────────────┘
          │ Supabase Client
          ↓
┌─────────────────────────────┐
│      Supabase Project       │
│                             │
│  ┌─────────────────────┐   │
│  │  PostgreSQL         │   │
│  │  - ux_analysis      │   │
│  │  - recordings       │   │
│  │  - validations      │   │
│  │  - collections      │   │
│  └─────────────────────┘   │
│                             │
│  ┌─────────────────────┐   │
│  │  Row Level Security │   │
│  │  (RLS Policies)     │   │
│  └─────────────────────┘   │
└─────────────────────────────┘

Key Design Decisions

• Transport: stdio (standard input/output) for Claude Desktop integration

• Authentication: API keys stored as SHA-256 hashes, never plaintext

• Rate Limiting: PostgreSQL function check_mcp_rate_limit() prevents abuse

• Logging: Winston with configurable log levels

• Error Handling: Graceful failures with user-friendly error messages

🧪 Testing

Validate MCP Server

# Install MCP Inspector
npm install -g @modelcontextprotocol/inspector

# Test server
npx @modelcontextprotocol/inspector node dist/index.js

Test Tool Calls

# Start server in dev mode
npm run dev

# In another terminal, send test queries
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | node dist/index.js

📚 Documentation

• DEPLOYMENT_GUIDE.md - Production deployment, Docker, environment setup

• SECURITY.md - Security policy, vulnerability reporting

• SETUP_COMPLETE.md - Detailed setup walkthrough

🤝 Contributing

Contributions are welcome! Please:

1. Fork the repository

2. Create a feature branch (git checkout -b feature/amazing-feature)

3. Commit your changes (git commit -m 'feat: Add amazing feature')

4. Push to the branch (git push origin feature/amazing-feature)

5. Open a Pull Request

Development Setup

# Clone your fork
git clone https://github.com/YOUR-USERNAME/mcp-research-insights.git
cd mcp-research-insights

# Install dependencies
npm install

# Run in development mode (auto-reload)
npm run dev

# Run tests
npm test

# Build for production
npm run build

🐛 Troubleshooting

MCP Server Not Appearing in Claude Desktop

1. Check ~/.claude/mcp.json syntax (valid JSON)

2. Verify absolute path to dist/index.js

3. Restart Claude Desktop completely

4. Check logs: ~/Library/Logs/Claude/mcp-research-insights.log

"SUPABASE_URL must be set" Error

• Ensure .env file exists in project root

• Verify environment variables in mcp.json are correct

• Check SUPABASE_URL format: https://xxx.supabase.co (no trailing slash)

"Unauthorized" or "RLS policy violation"

• Verify SUPABASE_SERVICE_ROLE_KEY (not anon/public key)

• Check RLS policies allow service role access

• Confirm tables exist in public schema

Rate Limit Exceeded

• Default: 100 requests/minute per API key

• Increase via MAX_REQUESTS_PER_MINUTE in .env

• Check rate limit logs: grep "rate limit" ~/Library/Logs/Claude/mcp-research-insights.log

📊 Use Cases

Product Managers

• Aggregate feature requests across 1000+ customer calls

• Track sentiment trends for specific features

• Prioritize roadmap based on customer pain points

UX Researchers

• Extract themes from user interviews at scale

• Validate research findings with confidence scores

• Export insights for cross-functional sharing

Customer Success Teams

• Identify at-risk accounts from support call patterns

• Track product adoption challenges

• Surface competitive threats early

Sales Teams

• Analyze objection patterns in discovery calls

• Understand why deals are won/lost

• Competitive intelligence from customer conversations

🔗 Related Projects

• Model Context Protocol - Official MCP documentation

• Claude Desktop - Download Claude Desktop app

• Supabase - Open source Firebase alternative

• SoundScribe - AI-powered call analysis platform

📄 License

MIT License - see LICENSE for details.

🙏 Acknowledgments

Built with:

• Model Context Protocol SDK

• Supabase JS Client

• Winston Logger

• TypeScript

💬 Support

• Issues: GitHub Issues

• Security: See SECURITY.md for reporting vulnerabilities

• Discussions: GitHub Discussions

Made with ❤️ by ECI Software Solutions