# StoreSignal MCP Server

mcp-name: io.github.anthesiallc/storesignal

A [Model Context Protocol](https://modelcontextprotocol.io) server that exposes
the [StoreSignal API](https://storesignal.anthesia.io) as tools, so any MCP
client (Claude Desktop, Cursor, ChatGPT connectors, or an agent framework) can
analyze Shopify stores and run market intelligence queries conversationally.

It's a thin wrapper: each tool maps to one StoreSignal REST endpoint. All the
data work happens in the API.

## Tools

| Tool | What it does |
|------|--------------|
| `analyze_store` | Full structured profile for a Shopify store URL (apps, CDN, security headers, schema.org, classification, revenue estimate) |
| `compare_stores` | Side-by-side comparison of 2-5 stores (shared apps, exclusive apps, tier) |
| `find_stores_using_app` | Paginated list of every analyzed store running a specific app |
| `list_apps` | All 278 apps in the catalog, optionally filtered by category |
| `app_adoption` | Top apps by adoption % across the corpus, optionally filtered by category |
| `app_vs_app` | Head-to-head: install counts, overlap, co-install rate, bidirectional cross-adoption |
| `industry_overview` | Per-vertical stats: store count, median price, top countries, top apps, tier mix |
| `store_census` | Whole-corpus stats (19,647 stores, 20 industries, app/tier/type breakdowns) |
| `get_usage` | Current billing period usage and plan limit |

## Get an API key

Free tier is 250 calls/month, no credit card:

```bash
curl -X POST https://storesignal.anthesia.io/api/v1/signup \
  -H 'Content-Type: application/json' \
  -d '{"email":"you@example.com"}'
```

The key comes back in the `api_key` field of the response.

## Install and run

The easiest way is with [uv](https://docs.astral.sh/uv/) (no manual venv needed):

```bash
# stdio transport (default — for Claude Desktop, Cursor, most local clients)
STORESIGNAL_API_KEY=ss_your_key uvx storesignal-mcp

# streamable-HTTP transport (for remote / web clients)
STORESIGNAL_API_KEY=ss_your_key uvx storesignal-mcp --http
```

Or install with pip into its own environment:

```bash
pip install storesignal-mcp
STORESIGNAL_API_KEY=ss_your_key storesignal-mcp
```

> Note: install into a dedicated environment. The `mcp` SDK requires a newer
> `starlette` than the StoreSignal API app pins, so the two will conflict if
> installed together.

Environment variables:

- `STORESIGNAL_API_KEY` (required) — your StoreSignal API key.
- `STORESIGNAL_BASE_URL` (optional) — defaults to `https://storesignal.anthesia.io`.
- `STORESIGNAL_TIMEOUT` (optional) — request timeout in seconds, default `60`.

## Client configuration

### Claude Desktop

Add to `claude_desktop_config.json` (Settings → Developer → Edit Config):

```json
{
  "mcpServers": {
    "storesignal": {
      "command": "uvx",
      "args": ["storesignal-mcp"],
      "env": { "STORESIGNAL_API_KEY": "ss_your_key" }
    }
  }
}
```

### Cursor

Add the same block to `~/.cursor/mcp.json` (or the project `.cursor/mcp.json`).

### Smithery (hosted, no install)

The server is hosted on [Smithery](https://smithery.ai/server/anthesiallc/storesignal),
so MCP clients that support Smithery can connect without installing anything.
You provide your StoreSignal API key in the Smithery config and it routes to
the server.

### LangChain / LangGraph

Any LangChain or LangGraph agent can use these tools through
[`langchain-mcp-adapters`](https://github.com/langchain-ai/langchain-mcp-adapters):

```python
# pip install langchain-mcp-adapters langgraph "langchain[anthropic]"
from langchain_mcp_adapters.client import MultiServerMCPClient

client = MultiServerMCPClient(
    {
        "storesignal": {
            "transport": "stdio",
            "command": "uvx",
            "args": ["storesignal-mcp"],
            "env": {"STORESIGNAL_API_KEY": "ss_your_key"},
        }
    }
)
tools = await client.get_tools()
# hand `tools` to a LangGraph/LangChain agent, e.g.
# from langgraph.prebuilt import create_react_agent
# agent = create_react_agent("anthropic:claude-opus-4-8", tools)
```

LlamaIndex works the same way via its MCP tool spec.

## Example agent conversations

> "What apps does Allbirds use?"
> → `analyze_store("https://www.allbirds.com")`

> "Compare the tech stacks of Brooklinen and Bombas."
> → `compare_stores(["https://brooklinen.com", "https://bombas.com"])`

> "Which Shopify stores are running Judge.me?"
> → `find_stores_using_app("judge-me")`

> "What are the top email-marketing apps on Shopify?"
> → `app_adoption(category="Email Marketing")`

> "Compare Klaviyo to Omnisend."
> → `app_vs_app("klaviyo", "omnisend")`

> "Tell me about the Beauty vertical."
> → `industry_overview("Beauty")`

## Develop from source

```bash
git clone https://github.com/anthesiallc/storesignal-mcp && cd storesignal-mcp
python -m venv .venv
.venv/Scripts/python -m pip install -e ".[http]"   # Windows; [http] adds uvicorn for --http
# .venv/bin/pip install -e ".[http]"                # macOS/Linux
STORESIGNAL_API_KEY=ss_your_key .venv/Scripts/python -m storesignal_mcp.server
```

## Notes

- Data is extracted only from publicly accessible Shopify storefront endpoints.
- Not affiliated with Shopify Inc.
- The LLM-classification endpoints (industry / store type / growth stage) are
  intentionally not exposed as MCP tools. The agent calling MCP is already an
  LLM and can reason about the raw corpus data itself — exposing them would
  waste tokens on a round trip to OpenAI.