SCP Local MCP Server

A Model Context Protocol (MCP) server that provides AI assistants like Claude with secure access to customer data through the Shopper Context Protocol (SCP).

What is this?

This MCP server acts as a bridge between AI assistants and e-commerce systems that implement the SCP protocol. It enables Claude Desktop and other MCP clients to:

• Securely authorize access to customer accounts using OAuth 2.0 with PKCE
• Retrieve order history, loyalty points, active offers, and shopping preferences
• Discover SCP endpoints for merchants via DNS or well-known URIs
• Store and manage encrypted authentication tokens locally

All customer data requests are authenticated and authorized by the merchant's SCP server, ensuring privacy and security.

Quick Start with npx

The easiest way to use this server is with npx - no installation required!

With Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "scp": {
      "command": "npx",
      "args": ["-y", "@shoppercontextprotocol/local-mcp-server"]
    }
  }
}

On Windows, the config file is located at: %APPDATA%\Claude\claude_desktop_config.json

Testing with a Local Development Server

If you're developing an SCP server locally, you can configure the MCP server to point to your test endpoint:

{
  "mcpServers": {
    "scp": {
      "command": "npx",
      "args": ["-y", "@shoppercontextprotocol/local-mcp-server"],
      "env": {
        "SCP_TEST_ENDPOINT": "http://localhost:8787/v1"
      }
    }
  }
}

This bypasses DNS discovery and directs all requests to your local test server.

Installation (Alternative)

For development or if you prefer a local installation:

# Install globally
npm install -g @shoppercontextprotocol/local-mcp-server

# Or install locally for development
git clone <repository>
cd local_mcp
npm install
npm run build

Usage

With Claude Desktop (Local Installation)

{
  "mcpServers": {
    "scp": {
      "command": "scp-mcp-server"
    }
  }
}

Or with a local build:

{
  "mcpServers": {
    "scp": {
      "command": "node",
      "args": ["/absolute/path/to/local_mcp/dist/index.js"]
    }
  }
}

Direct Usage

# If installed globally
scp-mcp-server

# Or with local build
npm start

Development

npm run dev    # Watch mode
npm run build  # Production build
npm test       # Run tests

Configuration

The server stores configuration in ~/.scp/config.json. It will be created automatically on first run with these defaults:

{
  "dns_resolver": "1.1.1.1",
  "dns_cache_ttl": 86400,
  "poll_interval": 2,
  "max_poll_attempts": 150,
  "token_refresh_threshold": 300,
  "request_timeout": 30000,
  "demo_mode": true,
  "demo_endpoint": "http://localhost:8787/v1"
}

Configuration Options

• dns_resolver: DNS server to use for SCP endpoint discovery (default: Cloudflare's 1.1.1.1)
• dns_cache_ttl: How long to cache discovered endpoints in seconds (default: 24 hours)
• poll_interval: Seconds between polling attempts during OAuth flow (default: 2)
• max_poll_attempts: Maximum number of polling attempts (default: 150 / 5 minutes)
• token_refresh_threshold: Seconds before expiry to refresh tokens (default: 300 / 5 minutes)
• request_timeout: HTTP request timeout in milliseconds (default: 30000 / 30 seconds)
• demo_mode: Enable demo mode (default: true)
• demo_endpoint: Endpoint to use in demo mode (default: http://localhost:8787/v1)

Testing with a Development Server

There are multiple ways to point the MCP server to your test SCP server:

Option 1: Environment Variable (Recommended for npx)

Set SCP_TEST_ENDPOINT when running the server:

# Direct usage
SCP_TEST_ENDPOINT=http://localhost:8787/v1 scp-mcp-server

# With npx
SCP_TEST_ENDPOINT=http://localhost:8787/v1 npx @shoppercontextprotocol/local-mcp-server

# In Claude Desktop config (see Quick Start section above)

Option 2: Demo Mode Configuration

Edit ~/.scp/config.json:

{
  "demo_mode": true,
  "demo_endpoint": "http://localhost:8787/v1"
}

By default, demo mode is enabled and directs all SCP requests to the demo endpoint. This is useful for local testing without needing DNS records.

Option 3: Production Mode

To use real DNS-based discovery for production merchants:

{
  "demo_mode": false
}

Priority Order:

1. SCP_TEST_ENDPOINT environment variable (highest priority)
2. Demo mode configuration
3. DNS-based discovery (lowest priority)

Data Storage

• Tokens: ~/.scp/tokens.db (SQLite, encrypted)
• Config: ~/.scp/config.json

MCP Tools

• scp_authorize - Authorize access to a merchant
• scp_check_authorization - Check authorization status
• scp_revoke_authorization - Revoke access to a merchant
• scp_discover - Discover SCP endpoint for a domain

MCP Resources

• scp://{domain}/orders - Order history
• scp://{domain}/loyalty - Loyalty status
• scp://{domain}/offers - Active offers
• scp://{domain}/preferences - Customer preferences
• scp://{domain}/intents - Shopping intents

How to Use in Claude Desktop

After adding the MCP server to your Claude Desktop config and restarting Claude, you can interact with SCP-enabled merchants:

First Time: Authorize Access

Can you help me authorize access to my Boot Barn account? 
My email is customer@example.com

Claude will use the scp_authorize tool to:

1. Discover the SCP endpoint for bootbarn.com
2. Initiate OAuth authorization with a magic link
3. The magic link will be sent to your email
4. Poll for authorization completion
5. Store encrypted tokens locally

Access Your Data

Once authorized, you can ask Claude to retrieve your data:

What are my recent B…