{
  "markdown": "<p align=\"center\">\n  <img src=\"assets/logo.png\" width=\"72\" alt=\"SpreshApp logo\" />\n</p>\n\n<h1 align=\"center\">spreshapp-mcp</h1>\n\n<p align=\"center\">\n  MCP server that connects Claude to SpreshApp's Facebook ad intelligence platform.\n  <br />\n  <a href=\"https://www.npmjs.com/package/spreshapp-mcp\"><img src=\"https://img.shields.io/npm/v/spreshapp-mcp\" alt=\"npm version\" /></a>\n  <img src=\"https://img.shields.io/badge/node-%3E%3D20-brightgreen\" alt=\"Node 20+\" />\n  <img src=\"https://img.shields.io/badge/MCP-compatible-blue\" alt=\"MCP compatible\" />\n</p>\n\n---\n\nAsk Claude to research competitors, decode winning ad angles, track brand ad history, and analyze your saved ad library, all directly from your Claude Desktop or Claude Code session.\n\n<p align=\"center\">\n  <img src=\"assets/feature-mcp.png\" alt=\"SpreshApp MCP in Claude Code\" width=\"800\" />\n</p>\n\n## Requirements\n\n- Node.js >= 20\n- A [SpreshApp](https://spreshapp.com) account\n\n## Setup\n\n### Claude Desktop\n\nAdd this to your `claude_desktop_config.json` (macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"spreshapp\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"spreshapp-mcp\"]\n    }\n  }\n}\n```\n\nRestart Claude Desktop after saving.\n\n### Claude Code\n\n```bash\nclaude mcp add spreshapp -- npx -y spreshapp-mcp\n```\n\n### VS Code (with MCP extension)\n\n```json\n{\n  \"mcp\": {\n    \"servers\": {\n      \"spreshapp\": {\n        \"command\": \"npx\",\n        \"args\": [\"-y\", \"spreshapp-mcp\"]\n      }\n    }\n  }\n}\n```\n\n## Authentication\n\nAuthenticate once before starting the MCP server:\n\n```bash\nnpx -y spreshapp-mcp login\n```\n\nThis opens your browser to log in with your SpreshApp account (OAuth 2.0 with PKCE). After login, credentials are saved to `~/.spreshapp/credentials.json` (file mode 600) and refreshed automatically before each session.\n\nFor headless or remote agent environments, use a SpreshApp API key from the dashboard instead of browser OAuth:\n\n```bash\nnpx -y spreshapp-mcp login --no-browser\n```\n\nThis prints setup instructions for the user and agent. The user can create or copy a key at [spreshapp.com/app/api-access](https://spreshapp.com/app/api-access). Keys start with `sk_sprs_`.\n\nSet the key in the MCP server environment:\n\n```bash\nSPRESHAPP_API_KEY=sk_sprs_... npx -y spreshapp-mcp\n```\n\nOAuth token variables are still supported for advanced setups: `SPRESHAPP_ACCESS_TOKEN`, `SPRESHAPP_REFRESH_TOKEN`, `SPRESHAPP_CLIENT_ID`, and `SPRESHAPP_TOKEN_EXPIRES_AT`.\n\nCheck auth status:\n\n```bash\nnpx -y spreshapp-mcp status\n```\n\nTo log in again:\n\n```bash\nnpx -y spreshapp-mcp logout\nnpx -y spreshapp-mcp login\n```\n\n## Available Tools\n\n### Ad tools\n\n| Tool | Description |\n|------|-------------|\n| `ad_search` | Search Facebook ads by keyword, niche, or industry |\n| `ad_search_expand_query` | Expand a search query to surface more relevant ads |\n| `ad_get` | Fetch full details for a specific ad |\n| `ad_get_analysis` | Retrieve saved AI analysis for an ad |\n| `ad_analyze` | Run AI analysis on any ad |\n| `ad_analyze_batch` | Analyze multiple ads in one call |\n| `ad_chat` | Chat with Claude about an ad's creative strategy |\n\n### Brand tools\n\n| Tool | Description |\n|------|-------------|\n| `brand_search` | Search for brands in SpreshApp |\n| `brand_get_overview` | Get a brand's full profile and stats |\n| `brand_get_status` | Get the current tracking status for a brand |\n| `brand_get_ad_history` | Get historical ad volume data for a brand |\n| `brand_list_active_ads` | List all ads a brand is currently running |\n| `brand_follow` | Start tracking a brand |\n\n### Library tools\n\n| Tool | Description |\n|------|-------------|\n| `search_ads` | Search your saved ad library |\n| `get_folder_ads` | Get ads from a specific folder |\n| `list_folders` | List all your saved folders |\n| `get_tags` | List tags used across your library |\n| `get_pages` | List saved Facebook pages |\n\n## Example prompts\n\n```\nFind 10 high-performing Facebook video ads in the fitness niche and summarize the angles used.\n```\n\n```\nResearch Nike's current Facebook ad strategy, how many ads are they running and what are the themes?\n```\n\n```\nOpen my \"Inspiration\" folder and identify the top 3 creative hooks.\n```\n\n```\nTrack the brand glossier.com and show me their ad history over the last 30 days.\n```\n\n## Troubleshooting\n\n| Symptom | Fix |\n|---------|-----|\n| Browser did not open | Copy the URL printed to the terminal and open it manually |\n| \"Authentication expired\" error | Delete `~/.spreshapp/credentials.json` and re-run |\n| \"Not subscribed to any plan\" | Visit [spreshapp.com/pricing](https://spreshapp.com/pricing) |\n| \"Daily limit reached\" | Quota resets at midnight UTC, or upgrade your plan |\n| \"Feature not available\" | Your current plan does not include this tool, upgrade at [spreshapp.com/pricing](https://spreshapp.com/pricing) |\n\n## License\n\nUNLICENSED — proprietary software. See [spreshapp.com](https://spreshapp.com) for terms.\n",
  "bytes": 4941,
  "sha": "180d3ddc95bdde8a30aab7a103265f987e26d57b20de6052ea7d2dc6f8521e74",
  "repo_slug": "prashantbtkl/spresh-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_prashantbtkl_spresh_mcp_d67e83c5/readme"
}