scree MCP server
Commit Nov 4, 2026Enables semantic and keyword search over markdown files in repositories or notes folders for AI clients via MCP.
Also known as jrapakko/scree
- Stars
- 0
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- 0.4.1
- Last commit
- Nov 4, 2026
- License
- MIT
What is scree MCP?
scree enables semantic and keyword search over markdown files in repositories or notes folders for AI clients via MCP.
Summary generated from the project's README
About scree MCP server
Scree provides local semantic and keyword search capabilities for markdown files within repositories or notes folders. It is designed specifically for AI clients like Claude Code to retrieve relevant information without loading entire files into context. The server works by splitting markdown content by headings, generating embeddings via an API, and storing the results in a local SQLite database. Each index is maintained per folder, ensuring that the markdown files remain the single source of truth.
To use this server, developers need Go 1.26 and an OpenRouter API key. The setup involves building a static binary and configuring the key through the scree CLI. When integrated with Claude Code via MCP, the server can be run as a project-scoped tool. It supports different search modes, including an automatic mode that switches between semantic and keyword search based on the query type. Users can manage indexing with commands like doctor, reindex, and watch to keep the local database current.
What you can do with it
- 1Retrieve specific documentation snippetsAsk the AI to find the exact lines in a markdown file that explain a specific procedure.
- 2Estimate indexing costs and file exclusionsVerify which files will be ignored and how much the embedding API will cost before starting a full index.
- 3Maintain a live index of notesKeep the search index updated automatically as markdown files change in a folder.
Written from the project's README. Every use case is checked against a quote from it.
How to install scree MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall scree MCP in Claude Code
$ claude mcp add --env 'OPENROUTER_API_KEY=<YOUR_OPENROUTER_API_KEY>' scree -- docker run -i --rm ghcr.io/jrapakko/scree:0.4.1Install scree MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"scree": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"ghcr.io/jrapakko/scree:0.4.1"
],
"env": {
"OPENROUTER_API_KEY": "<YOUR_OPENROUTER_API_KEY>"
}
}
}
}Install scree MCP in VS Code
.vscode/mcp.json
{
"servers": {
"scree": {
"type": "stdio",
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"ghcr.io/jrapakko/scree:0.4.1"
],
"env": {
"OPENROUTER_API_KEY": "<YOUR_OPENROUTER_API_KEY>"
}
}
}
}Install scree MCP in VS Code CLI
$ code --add-mcp '{"name":"scree","type":"stdio","command":"docker","args":["run","-i","--rm","ghcr.io/jrapakko/scree:0.4.1"],"env":{"OPENROUTER_API_KEY":"<YOUR_OPENROUTER_API_KEY>"}}'Install scree MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"scree": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"ghcr.io/jrapakko/scree:0.4.1"
],
"env": {
"OPENROUTER_API_KEY": "<YOUR_OPENROUTER_API_KEY>"
}
}
}
}Install scree MCP in Codex
$ codex mcp add scree --env 'OPENROUTER_API_KEY=<YOUR_OPENROUTER_API_KEY>' -- docker run -i --rm ghcr.io/jrapakko/scree:0.4.1Install scree MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.scree] command = "docker" args = ["run", "-i", "--rm", "ghcr.io/jrapakko/scree:0.4.1"] [mcp_servers.scree.env] OPENROUTER_API_KEY = "<YOUR_OPENROUTER_API_KEY>"
Install scree MCP in Gemini CLI
$ gemini mcp add -s user -e 'OPENROUTER_API_KEY=<YOUR_OPENROUTER_API_KEY>' scree docker -- run -i --rm ghcr.io/jrapakko/scree:0.4.1Install scree MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"scree": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"ghcr.io/jrapakko/scree:0.4.1"
],
"env": {
"OPENROUTER_API_KEY": "<YOUR_OPENROUTER_API_KEY>"
}
}
}
}Configuration
OPENROUTER_API_KEYRequiredSecretOpenRouter API key, used to embed the notes when indexing and each query when searching.
CGO_ENABLEDSCREE_NOTES_DIR
| Name | Description | |
|---|---|---|
| OPENROUTER_API_KEY | OpenRouter API key, used to embed the notes when indexing and each query when searching. | RequiredSecret |
| CGO_ENABLED | — | |
| SCREE_NOTES_DIR | — |
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablejrapakko/scree is public and reachablegithub.com/jrapakko/scree ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-04github.com/jrapakko/scree ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubscree
Local semantic search over the markdown in your repos and notes, served to Claude Code over MCP.
Scree splits markdown by heading, embeds the pieces through an API, and stores them in a SQLite file on disk, one index per folder. Claude Code asks for the few chunks that match a question instead of loading whole files. Each hit says which lines it came from, so Claude can read just those. The markdown stays the source of truth; an index can be deleted and rebuilt at any time.
See docs/SPEC.md for the design.
Quick start
You need Go 1.26 and an OpenRouter API key from https://openrouter.ai/settings/keys. The commands run from the root of this repo unless a step says otherwise.
-
Build a static binary (no CGO):
CGO_ENABLED=0 go build -trimpath -ldflags='-s -w' -o bin/scree ./cmd/scree -
Save the key in the settings file.
scree keyprompts for it without echoing it, so it never lands in your shell history or on screen, writes~/.config/scree/envwith mode 600, and makes one test call to the API:bin/scree keyIt keeps any other lines in the file and replaces an earlier key.
scree key < filereads the key from the first line of a file instead, and replaces a saved key only with-replace;-offlineskips the test call, and-checkmakes only the test call. Ctrl-C at the prompt saves nothing. To see Claude Code's OpenRouter costs apart from your own searches, save a second key withbin/scree key -mcp:scree mcpthen uses it, and everything else keeps the first (settings file). -
Install the binary:
mkdir -p ~/.local/bin install -m 755 bin/scree ~/.local/bin/Claude Code must find
screeon itsPATH. If~/.local/binisn't on it, add it in your shell profile. -
Check a repo before indexing it.
scree runloads the settings file and runs a scree command. From inside the repo:cd ~/code/myrepo scree run doctor -vdoctor -vlists every file that will be ignored and estimates the cost of indexing the rest. Add a.screeignoreor.gitignoreentry before indexing if anything private shows up as indexable. -
Turn scree on for the repo. From the repo's root:
claude mcp add scree --scope project -- scree mcpThis writes
.mcp.jsonwith"command": "scree", "args": ["mcp"], with no key and no paths, so commit it. Claude Code asks each person to approve a project server once. Every session in the repo then keeps the index current; the first session builds it in the background.serverefuses a repo whose own.mcp.jsondoesn't namescree mcp, so a repo without this entry is never indexed, even if scree is also registered elsewhere. Don't register scree at user scope anyway.Approving a project server means trusting the repo. Claude Code applies the
envof a repo's.mcp.json, includingPATH, before it starts the server, so a repo you approve decides which programscreeis, and that program gets your settings file. Approve scree only in repos whose.mcp.jsonyou trust, as you would any project server. To take that choice back for yourself, see absolute paths. -
Optional: a notes folder outside any repo. See A notes folder.
Build
Requires Go 1.26. No CGO. Tagged releases also publish prebuilt binaries for Linux, macOS and Windows (amd64 and arm64) on the GitHub releases page, a ghcr.io/jrapakko/scree image, and a Claude Desktop bundle, which scripts/mcpb.sh zips from the release's binaries.
CGO_ENABLED=0 go build -trimpath -ldflags='-s -w' -o bin/scree ./cmd/scree
Configure
Settings come from environment variables. The settings file is the one place to keep them, including the API key. Don't export the key in a shell profile. With OPENROUTER_API_KEY unset, a command run directly (scree search, doctor, reindex, watch) still uses the key in the settings file, by running as scree run would; see below.
| Variable | Default |
|---|---|
SCREE_DB |
$XDG_DATA_HOME/scree/indexes/<folder>-<hash>/index.db, one per folder (or -db) |
SCREE_MODEL |
openai/text-embedding-3-small |
SCREE_DIMENSIONS |
512; 0 uses the model's default size |
SCREE_EMBED_URL |
https://openrouter.ai/api/v1/embeddings |
SCREE_MAX_FILE_BYTES |
1048576; larger files are skipped |
SCREE_FIRST_SYNC_MB |
50; a Claude Code session or watch won't start the first index of a folder with more markdown than this (0 = no limit); scree reindex always does |
SCREE_ZDR |
1; set 0 for endpoints other than OpenRouter |
SCREE_HTTP_TOKEN |
none; required with serve -allow-remote, and enforced on loopback if set |
SCREE_PAGER |
less -FRX from /usr/local/bin, /usr/bin or /bin; the pager for scree search's text view on a terminal, run without a shell: an absolute path or a name in those folders (never looked up on PATH), then its arguments. Set it empty for none |
SCREE_COLORS |
word=1:match=1;33:link=36:lineno=2; the text view's colours as SGR codes (digits and ; only) for the word headings, the matched words, the locations and the line numbers. match= turns one off |
OPENROUTER_API_KEY |
none; when unset and the settings file holds one (scree key writes it there), search, reindex, doctor and watch run as scree run would. Without a key (unset or empty), notes are indexed for keyword search only and auto search runs keyword |
SCREE_MCP_API_KEY |
none; read only from the settings file (scree key -mcp writes it), and only by scree mcp, which passes it to serve as OPENROUTER_API_KEY instead of the file's own. Commands run directly and scree run never use it |
$XDG_DATA_HOME defaults to ~/.local/share; a relative value is ignored. With neither it nor an absolute home directory, scree refuses to open an index unless -db names one.
Which folder. -notes <dir> names it on the command line. Without it, CLI commands use the git root of the current directory, or the current directory outside git. Under Claude Code, serve indexes the git root of the working directory Claude Code starts it in (the project, or the active worktree), refuses -notes, -db and SCREE_DB, and requires CLAUDE_PROJECT_DIR to be in the same repo; a .mcp.json can set environment variables but not the working directory. It also refuses a folder whose root .mcp.json names no scree mcp server. Outside Claude Code, serve has no default folder: pass -notes. A folder found automatically is refused if it is your home directory (from the password database, falling back to $HOME only if that lookup fails), a folder above it, or a filesystem root; on the command line, pass -notes to index it anyway. serve refuses such a folder even as -notes (a client such as Claude Desktop passes the folder a user picked) unless -allow-home is given. The check compares the folders themselves, not just their paths, so another path to your home folder (a bind mount, different letter case on macOS, /System/Volumes/Data/Users/…) is refused too. It only compares the chosen folder with your home folder and the folders above it, so a folder that holds a mount of your home somewhere inside it (as some containers and devcontainers set up) is not caught. Each index records its folder and refuses to be used for another one.
Changing the model or dimensions requires scree reindex -all. The index records which model built it and refuses to mix them.
Privacy
Every embedding request asks OpenRouter to route only to endpoints with zero data retention and data_collection: deny. A model with no such endpoint fails with a clear error naming the model, rather than falling back to one that keeps data. SCREE_ZDR=0 turns this off, which other OpenAI-compatible endpoints may need. Only chunk text, with its path and heading, is sent to the API; keyword search runs locally.
Ignoring files
An ignored file is never read for indexing, never sent to the embedding API, never returned by search, and refused by read_doc and reindex. Four layers decide:
- Built-in: hidden files and folders, except the root
.claude/(not.claude/worktrees/),.github/,.gitlab/,.gitea/,.forgejo/,.cursor/,.codex/,.gemini/,.windsurf/,.circleci/and.buildkite/; anything that isn't.md,.markdownor.mdc; symlinks that lead outside the folder; files overSCREE_MAX_FILE_BYTES; non-regular files such as FIFOs, which are never opened and whichdoctorreports as unreadable; and names with control characters. .gitignore: in a git repo, everything git ignores (nested.gitignorefiles,.git/info/exclude, your global excludes file). Ignored folders such asnode_modules/are never read, and nested repositories are skipped. A tracked file that matches a pattern is still ignored.-gitignore=falseturns this layer off..screeignoreat the root of the indexed folder, in gitignore syntax.- Front matter:
scree: ignorein a file's front matter.
# .screeignore
journal/
**/private-*.md
/inbox/scratch.md
!journal/public.md
include-hidden .name/ in .screeignore indexes another root hidden folder, and a pattern like /.cursor/ drops one of the defaults. A ! rule re-includes files inside an excluded folder, but never a file that a rule matched by name, so *.private.md stays ignored even under !archive/2024/; doctor -v lists what ! re-included. If .screeignore can't be read, is a symlink, or has a line scree can't parse, nothing is indexed until it is fixed; doctor names the bad lines by number.
---
scree: ignore
---
Run scree doctor -v to see what each layer ignores before relying on a pattern. The full rules are in docs/SPEC.md.
Use
scree key # save the API key in the settings file
scree key -mcp # optional: a separate key for scree mcp (Claude Code)
scree doctor # check config, index, and the API
scree doctor -v # also list every ignored file, and check the keyword index
scree reindex # index new and changed files
scree reindex docs/a.md # re-index one file
scree reindex -all # rebuild from scratch
scree search "how do I rotate the backup keys"
scree search -mode keyword PURGE_OLD_RECORDS # exact words, no API call
scree search -format text "ci seed" # hits grouped by query word (the default on a terminal)
scree search -no-pager "ci seed" # the same, printed without the pager
scree search -format json "…" # one JSON object per hit
scree search -format grep "…" # path:line:text, for fzf or vim -q
scree watch # keep the index current (run as a service)
scree serve -notes . # MCP over stdio, from a terminal
scree serve -notes . -http 127.0.0.1:7077 # MCP over HTTP, loopback only
scree indexes # list per-folder indexes; -prune deletes ones whose folder is gone
Every command but indexes and key takes -notes <dir>, -db <file> and -gitignore=false. serve needs -notes outside Claude Code. From a terminal, search, reindex, doctor and watch run as scree run <command> would whenever OPENROUTER_API_KEY is unset and the settings file holds a key; scree run loads the file in any case, for example scree run search "…".
Search modes
scree search -mode and the search_docs tool's mode take:
auto(the default):semantic, unless the query has an identifier-like word, a word with a letter plus_or a digit, such asPURGE_OLD_RECORDS,psycopg_pool,R7-Q2orv2, or a word from the folder's code vocabulary (below); thenhybrid.ID,API,2026andwell-knowndon't count.hybrid: a vector search and an SQLite FTS5 keyword search over chunk text, heading and path, merged by reciprocal rank fusion, so exact names rank first.semantic: vectors only.keyword: FTS5 only. It makes no API call, so it works without a key or while the API is down. A failed embedding call says so.
With no API key, auto runs keyword and its output ends with [mode: auto → keyword: no API key; run scree key, or set OPENROUTER_API_KEY]; -mode semantic or hybrid is an error. serve never reads the settings file itself; under Claude Code it says the same (scree mcp passes the file's key), and elsewhere, as from Claude Desktop, add an OpenRouter API key in the extension's settings, set OPENROUTER_API_KEY, or start through scree mcp. On Windows it drops the scree key and scree mcp parts.
Without a key, indexing still works: each note is chunked and stored for keyword search, with no API call, and reindex reports those files as indexed (N keyword only: no API key). Once a key is set, the next sync (scree reindex, or the writer starting) embeds exactly those files and no others. Until then, semantic and hybrid miss them and say so ([N files indexed for keyword search only; scree reindex embeds them]), and scree doctor counts them on its index line. An API error or outage with a key is not treated as no key: the file fails or waits for the API as before. A key the API rejects (401) is: from then on that process indexes for keyword search only, without asking the API again, auto runs keyword and says the embedding API rejected the API key; replace it: <hint>, and the next process with a working key embeds those files. A 403, which OpenRouter sends for an input its moderation flags, fails only that file, as other API errors do; the key is not taken as rejected.
Scree trims spaces and newlines around OPENROUTER_API_KEY. A value that is an unfilled ${...} placeholder, or that scree key would refuse (inner whitespace, control characters, quotes), counts as no key, with one log line that never shows the value.
On a private set of 16 plain-language and 7 identifier queries over real notes, auto kept plain-question file MRR at 0.89 while raising identifier MRR from 0.46 to 0.80. Always-on hybrid raised identifiers as much but cost plain questions, which is why it is not the default.
The code vocabulary catches names with no _ or digit, such as psycopg or PageFetcher. Each sync reads, under the same ignore rules as markdown but never inside a hidden folder (the .claude/-style allowlist is for markdown), the dependency names in requirements*.txt, pyproject.toml, package.json, go.mod and Cargo.toml, and the mixed-case names (PageFetcher, useState) in import statements and declarations of Python, JavaScript, TypeScript and Go files; vendored folders and unchanged files are skipped, and at most 20,000 files are opened per sync. Common words are kept out, even as package names: golang.org/x/sync adds only its full path, and a stoplist of about 350 words drops function words (how, the), package names that are ordinary words (sync, requests, next, config) and plain words written in mixed case (setUp, fileName); a word it misses can still send a plain question to hybrid. PageFetcher's in a query counts as PageFetcher. Only the lowercased names are kept, in the local index; code is never chunked, embedded or sent to the API. On two repos with code and docs, this raised results for questions naming code a little and sent no plain question to hybrid.
Routing uses the vocabulary alone, whether or not the notes contain the name: hybrid's keyword side matches every word of the query, so a question naming code gains even when the docs rarely name it. The extractor is line-based heuristics, not a parser, so it can misread, say, text from a string as a name; such a misread can at worst send a question to hybrid, and is never printed or embedded. scree doctor reports how many names were read and how many the notes also contain (pagefetcher matches PageFetcher; a dotted or slashed name such as golang.org/x/sync must match as a phrase), and -v shows a sample of the latter only; a name found only in code is never printed.
The query is never passed to FTS5 as syntax: each word becomes a quoted term. Words keep _ and -, so psycopg_pool is one term, and pool alone finds it only through the vector side.
Results
On a terminal, scree search prints a text view grouped by query word. Each hit is listed once, under the first query word its text, path or heading holds, as keyword search matches it: its heading and the lines that hold the word (at most 10, each cut at 160 characters), then its location, then every line of that range from the current file, numbered (read through the same ignore rules, cut at 3,500 bytes). Hits with no query word (usually semantic-only) and stale hits come last; a stale hit has no numbered lines.
seed:
### 5.1 Files
- `.forgejo/workflows/ci.yml`: build, test, and the seed from the run number
>docs/plan.md:189-191
>>189 ### 5.1 Files
>>190
>>191 - `.forgejo/workflows/ci.yml`: build, test, and the seed from the run number
other hits:
## Keys
>docs/keys.md:3-4
>>3 ## Keys
>>4 Rotate them yearly.
# Old notes
>docs/old.md (stale)
[mode: auto → hybrid]
A word matches whole tokens, as keyword search does, including inside a path written in a note (ci matches .forgejo/workflows/ci.yml) and across a line break. Each location is a link to the file in terminals that support OSC 8 links. The query words are coloured wherever they match in the excerpt and the numbered lines, and the word headings, locations and line numbers have their own colours (SCREE_COLORS). Set NO_COLOR or TERM=dumb to turn links and colours off (scree run search honours it). Use -mode keyword for a grep-like view with no semantic hits.
On a terminal the text view goes through a pager, so it starts at the top: less -FRX (it quits at once if the view fits on one screen, passes the colours and links, and leaves the text on screen when you quit), or SCREE_PAGER. less 566 and later pass OSC 8 links with -R; older versions show them as raw escapes, so use -no-pager or SCREE_PAGER= there. -no-pager, SCREE_PAGER= (set but empty), a pipe, or a pager that cannot start prints directly. Quitting the pager early is not an error. The pager runs with LESSCHARSET=utf-8 unless you set LESSCHARSET, so less shows characters such as → even without LANG. scree run search, and a direct scree search using the settings file's key, take SCREE_PAGER and SCREE_COLORS from the settings file only. They pass your TERM on only if it is a plain terminal name such as xterm-256color, and never TERMINFO, TERMINFO_DIRS or TERMCAP. Without a usable TERM the default less is not used, because less needs it.
Piped, or with -format xml, each hit is a <hit> element:
<hit n="1" path="docs/setup.md" lines="12-19" heading="Setup > Keys" score="0.912" match="both">
chunk text
</hit>
linesis the range of source lines the chunk came from, so Claude can read exactly those (read_doc(path, start, end)). If the file changed since it was indexed, search finds the chunk in the current file, exactly or ignoring whitespace changes, and reports the current range. If the text is gone, the hit hasstale="true"and nolines. Changed files are queued for re-indexing.matchsays which search found the hit:semantic,keywordorboth.scoreis the cosine similarity and is missing for keyword-only hits.- Identical chunks in several files, such as committed build copies, come back as one hit. The shown copy has the shortest path, and
also="docs/print/x.md:12-18, …"lists up to three others, withalso_more="N"for the rest. A listed copy whose file changed is relocated like the hit, or shown aspath:stale. Excluding build folders with.screeignoreis still better: it saves embedding cost. - In
automode the output ends with a line such as[mode: auto → hybrid].
-format json prints one object per line, the stable format for scripts and evals: {"n","mode","path","start","end","heading","score","match","stale","also","also_more"}, where mode is the mode that ran, start, end and score are null when absent, also is a list of {"path","start","end"} (with "stale":true on a copy whose text is gone), and also_more appears only when more copies exist.
-format grep prints path:line:text lines like grep -n: each line of a hit that holds a query word, or a semantic hit's first line, in rank order, each once, with control characters dropped. Pick a hit with fzf and open it in vim, or load all of them into vim's quickfix list:
sg() { scree search -format grep "$*" | fzf --delimiter : \
--preview 'n={2}; case $n in ""|*[!0-9]*) exit;; esac; sed -n "$(( n>5 ? n-5 : 1 )),+30p" -- {1}' \
--bind 'enter:become(n={2}; case $n in ""|*[!0-9]*) exit 1;; esac; vim "+$n" -- {1})'; }
vim --cmd 'set efm=%f:%l:%m' -q <(scree search -format grep "ci seed")
Paths are relative to the folder, so run these from its top. A folder you didn't write can choose its file names and text, so treat the fields as untrusted: check the line is a number and put -- before the path, as above, rather than pasting {1} or {2} into shell arithmetic or a command line, and give vim -q the %f:%l:%m error format, since its default one also picks up "file" line N: inside note text. scree leaves out hits whose path holds : or a control character (with a count on stderr) and starts a path beginning with - or + with ./.
scree MCP questions
How do I add scree MCP to Claude Code?
Run claude mcp add --env 'OPENROUTER_API_KEY=<YOUR_OPENROUTER_API_KEY>' scree -- docker run -i --rm ghcr.io/jrapakko/scree:0.4.1 in your terminal. Add --scope user to make it available in every project.
How do I add scree MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
How does scree handle privacy with embedding APIs?
It requests OpenRouter to route only to endpoints with zero data retention and data collection denied, sending only text chunks with their path and heading.
Can I use scree without an API key?
Yes, without a key, notes are indexed for keyword search only and the auto search mode defaults to keyword search.
How can I see which files will be ignored before indexing?
You can use the scree doctor -v command to list every file that will be ignored and estimate the indexing cost.