--- title: "OpenLore: One Markdown Knowledge Base for Every AI Agent" url: "https://mcpshelf.co/servers/openlore" description: "OpenLore serves a folder of Markdown to Claude Code, Codex, Cursor and CI over MCP and SSH, with per-person access rules. Install, connect and tools." updated: "2026-10-27" site: "MCP Shelf" --- # OpenLore > One folder of Markdown that every agent on a team can read, with access rules. Source: https://mcpshelf.co/servers/openlore Markdown: https://mcpshelf.co/servers/openlore.md Generated: 2026-10-27T13:22:14.344Z ## Facts - **Name:** OpenLore - **Tagline:** One folder of Markdown that every agent on a team can read, with access rules. - **Description:** OpenLore is an open source server that shares a folder of Markdown with AI agents over MCP, SSH and the web, so several agents and people can read the same files with their own access rules. - **Repository:** https://github.com/aakarim/OpenLore - **Install:** `claude mcp add --transport http openlore http://localhost:8080/mcp` - **Server URL:** http://localhost:8080/mcp - **Transport:** Streamable HTTP (remote) - **Auth:** Needs `openlore ` - **Tools exposed:** 2: `lore_bash`, `list_commands` - **Category:** Knowledge and work apps (https://mcpshelf.co/categories/knowledge-and-work) - **Stats:** 1.7K GitHub stars, last commit 27 Oct 2026, 0 upvotes on MCP Shelf - **Install check:** Needs your setup first - **Listed:** 2026-10-27 - **Page updated:** 2026-10-27 ## Full description ### What is OpenLore? **OpenLore is an open source server that shares a folder of Markdown with AI agents over MCP, SSH and the web, so several agents and people can read the same files with their own access rules.** OpenLore, by the GitHub user aakarim, serves a folder of Markdown files to agents so they all work from the same notes, runbooks and docs. Instead of a new search API, it gives them a small shell that understands the commands models already know, such as ls, cat, grep, find and jq, over a virtual file system. The same files are available over MCP, over SSH and in a web view. The shell is written in Go and cannot run programs or reach your real disk. It is read-only by default; you can allow publishing into set folders or full writes per docset, and give each person or agent its own view. It runs as a server, so a team can host one copy and point every agent at it. | | | | --- | --- | | Made by | aakarim and contributors | | GitHub | https://github.com/aakarim/OpenLore | | Licence | Apache-2.0 | | GitHub stars | 1.7K | | Last commit | 27 Oct 2026 | | Tools | 2 | | Runs on | Hosted | | Install check | Needs your setup first | | Category | [Knowledge and work apps](https://mcpshelf.co/categories/knowledge-and-work) | | Setup checked | 27 Oct 2026 | | Page updated | 27 Oct 2026 | **Our check:** It needs something our Linux test machine does not have (an account, a desktop app, a Mac or a running service), so on 27 Oct 2026 we read its tools from the source code instead of running this config. The shared database gave "npx openlore", an npm package by someone else for a different tool. OpenLore is a Go program installed from Homebrew or its GitHub releases. #### MCP Shelf take > OpenLore needs something our Linux test machine does not have (an account, an app or a service), so on 27 Oct 2026 we read its source and counted 2 tools. 1 of the 2 only read; the other 1 can change things. Other directories point at a package with the same name that belongs to someone else; the config on this page installs the real one. It sits 14th of 16 in its category on our shelf by GitHub stars (1.7K). — MCP Shelf tests (numbers from our own runs), tested on 27 Oct 2026 ### What tools does OpenLore have? We listed 2 tools on 27 Oct 2026. 1 only read; the rest can change things or run commands. | Tool | Kind | What it is for | | --- | --- | --- | | `lore_bash` | changes | Runs a command in OpenLore's restricted shell over the served files: ls, cat, grep, find, jq, sed and more, with pipes. Writes work only where the server allows them. | | `list_commands` | reads | Lists the commands the shell supports. | ### How do I install OpenLore? #### What you need first - The openlore program, from Homebrew or the GitHub releases - A folder of Markdown to serve 1. Install it with "brew install --cask aakarim/tap/lore", or download a release for Linux or Windows from GitHub. 2. Run "openlore ./docs" to serve a folder. MCP and the web view use port 8080, and SSH uses port 2222. 3. Add the config below to your client. For Claude Code, run "claude mcp add --transport http openlore http://localhost:8080/mcp". #### Claude Code Where: Your terminal, in the project folder ```bash claude mcp add --transport http openlore http://localhost:8080/mcp ``` Then tell your agents when to use it: ssh -p 2222 localhost agents >> AGENTS.md. Agents with a shell can also reach the same files over SSH without MCP. #### Cursor Where: ~/.cursor/mcp.json, or .cursor/mcp.json in a project ```json { "mcpServers": { "openlore": { "url": "http://localhost:8080/mcp" } } } ``` #### Claude Desktop Where: Settings → Connectors → Add custom connector ``` http://localhost:8080/mcp ``` Paste the URL and sign in if asked. Custom connectors depend on your plan. #### VS Code Where: .vscode/mcp.json in your project ```json { "servers": { "openlore": { "type": "http", "url": "http://localhost:8080/mcp" } } } ``` #### Windsurf Where: ~/.codeium/windsurf/mcp_config.json ```json { "mcpServers": { "openlore": { "serverUrl": "http://localhost:8080/mcp" } } } ``` #### ChatGPT Where: Not supported for a local copy A server on localhost is not reachable from ChatGPT. A team deployment, for example with the project's Render button, serves MCP over HTTPS with OAuth sign-in. Claude Code may mistake a command like grep -r / for a scan of your own disk, so allow mcp__openlore in its permissions and tell it in CLAUDE.md that / is the docs root. Running "ssh -p 2222 localhost agents" prints a ready-made note to add. Checked against the project's own install docs on 27 Oct 2026: https://github.com/aakarim/OpenLore#readme ### How do I configure OpenLore? | Setting | Kind | Required | What it does | | --- | --- | --- | --- | | `openlore ` | flag | yes | Serves that folder. Its contents appear at / to every agent that connects. Example: `openlore ./docs` | | `openlore.yml` | config | no | Server settings such as the SSH port, the MCP path and whether it needs sign-in, which file types are served and inbox limits. An example ships in the repository. | | `lore.json` | config | no | Roles and docsets: which folders make up each docset and who may read, publish or write it. | ### What can OpenLore read and change? **It can read** - The files in the folders you serve, filtered by each identity's grants **It can change** - Served files, only where a docset allows publishing or writing - Nothing on the machine outside the served folders **Safer setup:** Keep it read-only, which is the default, or allow only publishing into an inbox folder so agents cannot overwrite existing documents. ### Good for - Giving several agents and repositories the same up-to-date context - Sharing runbooks or a style guide with coding agents - Letting agents publish findings into a shared inbox folder ### OpenLore not working? Common fixes **Claude Code blocks or keeps asking about grep -r /** It thinks the command is for your own disk. Allow mcp__openlore in .claude/settings.json and tell it in CLAUDE.md that / is the OpenLore docs root. **The dashboard returns 404** Builds made with go install or a plain go build have no dashboard. Use Homebrew, a release download or make distribution. **Agents do not know when to use it** Run ssh -p 2222 localhost agents and add its output to AGENTS.md or CLAUDE.md. ### What are the alternatives to OpenLore? | Server | What it does | Tools | Runs on | Licence | Stars | | --- | --- | --- | --- | --- | --- | | [OpenLore](https://mcpshelf.co/servers/openlore) | One folder of Markdown that every agent on a team can read, with access rules. | 2 | Hosted | Apache-2.0 | 1.7K | | [Minutes](https://mcpshelf.co/servers/minutes) | Records and transcribes meetings on your device, then lets an assistant search them. | 34 | Your computer | MIT | 1.6K | | [Garmin Connect MCP](https://mcpshelf.co/servers/garmin) | Ask an assistant about your Garmin activities, sleep, recovery and training. | 20 | Your computer | MIT | 1.4K | | [Notion](https://mcpshelf.co/servers/notion) | Notion's own server: search, read and update pages and databases. | 24 | Hosted or your computer | MIT | 4.7K | | [MCP Atlassian (Jira and Confluence)](https://mcpshelf.co/servers/atlassian) | Jira issues and Confluence pages, Cloud or self-hosted. | 98 | Your computer | MIT | 6.1K | | [Basic Memory](https://mcpshelf.co/servers/basic-memory) | Long-term memory as plain Markdown files you own. | 27 | Your computer | AGPL-3.0-or-later | 4.4K | ### OpenLore FAQ #### How do I add OpenLore to Claude Code? Install it with brew install --cask aakarim/tap/lore, serve a folder with openlore ./docs, then run claude mcp add --transport http openlore http://localhost:8080/mcp. #### What is OpenLore for? Sharing one set of Markdown files with several agents, repositories or people, each with its own access. Agents read it through MCP, SSH or the web view using grep, find and jq. #### Does OpenLore use a vector database? No. Agents find things with grep, find and jq over plain Markdown, so there is no embedding step and the files stay readable by people. #### Is OpenLore free? Yes. It is Apache 2.0 licensed. Running it locally costs nothing; a team deployment costs whatever your hosting provider charges. #### Is OpenLore safe? It is read-only by default. You can allow agents to publish only into an inbox folder so they cannot overwrite existing documents, and a team server signs people in with passkeys or OAuth. #### Can OpenLore run on a server for a team? Yes. The repository includes deployment guides, including a one-click Render deploy, and gives each person or agent its own sign-in and write provenance. #### Why not just keep Markdown in my repository instead of OpenLore? For one agent in one repository, that is simpler. OpenLore helps when several agents, repositories or people need the same files with different access. #### Why does Claude Code keep asking about grep commands with OpenLore? OpenLore's lore_bash tool runs commands such as grep -r / inside the shared folder, which Claude Code may flag. They run against OpenLore's files, not your disk, so you can allow them for that server. Full docs on GitHub: https://github.com/aakarim/OpenLore ## Notes for agents Fetch these instead of parsing the HTML page: - llms.txt: https://mcpshelf.co/llms.txt - llms-full.txt: https://mcpshelf.co/llms-full.txt - ai.txt: https://mcpshelf.co/ai.txt - Full catalog (.md): https://mcpshelf.co/catalog.md - API spec: https://mcpshelf.co/openapi.json - MCP server: https://mcpshelf.co/mcp - MCP manifest: https://mcpshelf.co/.well-known/mcp.json - Developer docs: https://mcpshelf.co/developers MCP endpoint (Streamable HTTP, no key): https://mcpshelf.co/mcp. REST API: https://mcpshelf.co/api/v1.