Give your agents SurfSense as native tools
The SurfSense MCP server hands Claude, Cursor, or any MCP client the whole platform: scrape Reddit, YouTube, Google Maps, Google Search, and the open web, and search, read, and write your knowledge base. One API key, typed tools, pay as you go.
.cursor/mcp.json
{
"mcpServers": {
"surfsense": {
"command": "uv",
"args": ["run", "--directory", ".../surfsense_mcp",
"python", "-m", "surfsense_mcp"],
"env": {
"SURFSENSE_BASE_URL": "https://api.surfsense.com",
"SURFSENSE_API_KEY": "ss_pat_..."
}
}
}
}Works with Claude Code, Cursor, Claude Desktop, and any MCP client
From API key to agent tools in three steps
Create an API key
In SurfSense, go to Settings, then API, and create a key. Enable API access on the workspaces you want your agents to reach. That key is all the server needs.
Add the server to your client
Drop the config into Cursor's mcp.json, run claude mcp add for Claude Code, or paste it into Claude Desktop. Point it at the cloud or your own self-hosted instance.
Your agent has the tools
Every scraper and knowledge base operation shows up as a native, typed MCP tool. Your agent picks a workspace once and the server carries the context between calls.
Step-by-step setup for every agent
Pick your client, follow its two steps, and paste the config. Replace the placeholder path with your surfsense_mcp checkout and the key with one from API Playground → API Keys — or grab a pre-filled config from the playground itself.
- Run this command in a terminal (any directory).
- Start Claude Code and run /mcp — surfsense should be listed as connected.
Terminal
claude mcp add surfsense \
-e SURFSENSE_BASE_URL=https://api.surfsense.com \
-e SURFSENSE_API_KEY=ss_pat_your_key_here \
-- uv run --directory /path/to/SurfSense/surfsense_mcp python -m surfsense_mcpEvery tool the server exposes
The server is a thin layer over the SurfSense REST API: the same endpoints, the same billing, no backend code imported. Whatever ships in the API shows up here.
Live scrapers
Structured, current platform data. One returned item is one billable unit.
- surfsense_reddit_scrape
- surfsense_youtube_scrape
- surfsense_youtube_comments
- surfsense_google_maps_scrape
- surfsense_google_maps_reviews
- surfsense_google_search
- surfsense_web_crawl
- surfsense_list_scraper_runs
- surfsense_get_scraper_run
Knowledge base
Read and write the same knowledge base your SurfSense agents use.
- surfsense_search_knowledge_base
- surfsense_list_documents
- surfsense_get_document
- surfsense_add_document
- surfsense_upload_file
- surfsense_update_document
- surfsense_delete_document
Workspace selector
Pick a workspace once; every later call defaults to it.
- surfsense_list_workspaces
- surfsense_select_workspace
The SurfSense MCP server vs external MCP connectors
They are two sides of the same protocol. The MCP server on this page pushes SurfSense tools out to agents you already run in Claude, Cursor, or your own harness. External MCP connectors do the reverse: they pull outside tools like Notion, Slack, and Jira into your SurfSense agents. Use both and data flows in either direction.
SurfSense MCP server: frequently asked questions
Put live market data inside your agents
The MCP server is part of the SurfSense competitive intelligence platform. Start with $5 of free credit, no credit card required.
SurfSenseSurfSense