mirror of
https://github.com/MODSetter/SurfSense.git
synced 2026-07-08 22:22:17 +02:00
92 lines
3 KiB
Markdown
92 lines
3 KiB
Markdown
# SurfSense MCP Server
|
|
|
|
A [Model Context Protocol](https://modelcontextprotocol.io/) server that exposes
|
|
SurfSense to MCP clients like **Claude Code**, **Cursor**, and **Claude Desktop**.
|
|
It talks to a running SurfSense backend purely over its REST API using a SurfSense
|
|
API key — it imports no backend code and can point at any instance (local or
|
|
hosted) by changing two environment variables.
|
|
|
|
## Tools
|
|
|
|
**Search-space selector**
|
|
- `surfsense_list_workspaces` — list the workspaces (search spaces) you can access
|
|
- `surfsense_select_workspace` — pick the active workspace by name or id
|
|
|
|
**Scrapers (all platforms)**
|
|
- `surfsense_web_crawl`, `surfsense_google_search`, `surfsense_reddit_scrape`,
|
|
`surfsense_youtube_scrape`, `surfsense_youtube_comments`,
|
|
`surfsense_google_maps_scrape`, `surfsense_google_maps_reviews`
|
|
- `surfsense_list_scraper_runs`, `surfsense_get_scraper_run` — retrieve past
|
|
results in full (useful when a large result was truncated inline)
|
|
|
|
**Knowledge base**
|
|
- `surfsense_search_knowledge_base` — semantic + keyword search over stored content
|
|
- `surfsense_list_documents`, `surfsense_get_document`
|
|
- `surfsense_add_document`, `surfsense_upload_file`
|
|
- `surfsense_update_document`, `surfsense_delete_document`
|
|
|
|
Workspace-scoped tools default to the active workspace; pass `workspace` (a name
|
|
or id) to override for a single call. Ids never need to be typed by hand — the
|
|
model carries them between calls.
|
|
|
|
## Prerequisites
|
|
|
|
1. A running SurfSense backend (default `http://localhost:8000`).
|
|
2. A **SurfSense API key**: SurfSense → Settings → API → create key (`ss_pat_…`).
|
|
3. **API access enabled** on the workspace(s) you want to use (workspace settings).
|
|
|
|
## Setup
|
|
|
|
Uses [uv](https://github.com/astral-sh/uv):
|
|
|
|
```bash
|
|
cd surfsense_mcp
|
|
uv sync
|
|
uv run python -m surfsense_mcp.selfcheck # verify tools register correctly
|
|
```
|
|
|
|
## Connect it to a client
|
|
|
|
### Cursor
|
|
|
|
Add to `~/.cursor/mcp.json` (or a project `.cursor/mcp.json`):
|
|
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"surfsense": {
|
|
"command": "uv",
|
|
"args": ["run", "--directory", "/absolute/path/to/SurfSense/surfsense_mcp", "python", "-m", "surfsense_mcp"],
|
|
"env": {
|
|
"SURFSENSE_BASE_URL": "http://localhost:8000",
|
|
"SURFSENSE_API_KEY": "ss_pat_your_token_here"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### Claude Code
|
|
|
|
```bash
|
|
claude mcp add surfsense \
|
|
-e SURFSENSE_BASE_URL=http://localhost:8000 \
|
|
-e SURFSENSE_API_KEY=ss_pat_your_token_here \
|
|
-- uv run --directory /absolute/path/to/SurfSense/surfsense_mcp python -m surfsense_mcp
|
|
```
|
|
|
|
### Claude Desktop
|
|
|
|
Add the same `mcpServers` block as Cursor to
|
|
`claude_desktop_config.json` (Settings → Developer → Edit Config).
|
|
|
|
## Configuration
|
|
|
|
See `.env.example`. Secrets are passed as environment variables by the client;
|
|
never commit tokens.
|
|
|
|
## Backend dependency
|
|
|
|
`surfsense_search_knowledge_base` calls `POST /api/v1/documents/search-semantic`,
|
|
a thin endpoint that exposes the backend's existing hybrid retriever over REST.
|
|
All other tools use pre-existing SurfSense endpoints.
|