# Folio

> Folio is an open-source MCP server for knowledge and memory. Browse a folder of markdown and data live, with read-only MCP tools over it. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Pricing:** Open source
- **Platforms:** CLI, self-hosted, Web
- **Website:** https://jakubro.github.io/folio/
- **Repository:** https://github.com/jakubro/folio
- **MCP Registry name:** io.github.jakubro/folio
- **Categories:** knowledge and memory, files and documents
- **Listing updated:** 2026-11-14

## About

Folio first of all serves a folder in your browser: GitHub-flavoured markdown with math, highlighted code and diagrams, refreshed as you save. What distinguishes it is that it models the whole folder, remembering what you have already read and marking every block added, changed or removed since, flagging figures in prose that no longer match the data they quote, and reporting broken links and failing rules in one health view.

Data files such as CSV, JSON, Parquet and SQLite open as tables and trees, and documents can embed a table, chart, single value or SQL query that redraws when data changes. An MCP server, a JSON API and a language server expose the same model to agents and editors, and the registry describes the MCP tools as read-only. In Claude Code, a plugin installs the server plus an agent skill.

It needs Node.js 22.18 or later, runs locally on port 8640 by default, and keeps its own state under ~/.local/state/folio. Folio writes into the folder only what a FOLIO.md asks for. The licence is GPL v3.

## Features

- **Live rendering:** Shows markdown with math, code and diagrams, updated as files are saved.
- **Read tracking:** Marks blocks added, changed or removed since you last read a page.
- **Data in documents:** Embeds tables, charts, values and SQL queries from CSV, JSON, Parquet or SQLite.
- **Figure checks:** Flags numbers in prose that no longer match the data they quote.
- **Folder health view:** Lists broken links, missing includes and failing rules, also via folio check in CI.
- **History:** Compares git versions and saved versions block by block, with day or week digests.

## Good for

- Give an agent read-only access to a notes or docs folder
- Catch out-of-date numbers in written reports
- Catch up on what changed in a shared docs folder
- Check a docs folder for broken links in CI
- Explore CSV or SQLite data next to the writing about it

## Install

### Claude Code (Terminal)

```sh
claude mcp add folio -- npx -y @jakubro/folio
```

### Claude Desktop (claude_desktop_config.json)

```json
{
  "mcpServers": {
    "folio": {
      "command": "npx",
      "args": [
        "-y",
        "@jakubro/folio"
      ]
    }
  }
}
```

### Cursor (~/.cursor/mcp.json)

```json
{
  "mcpServers": {
    "folio": {
      "command": "npx",
      "args": [
        "-y",
        "@jakubro/folio"
      ]
    }
  }
}
```

### VS Code (.vscode/mcp.json)

```json
{
  "servers": {
    "folio": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@jakubro/folio"
      ]
    }
  }
}
```

### Windsurf (~/.codeium/windsurf/mcp_config.json)

```json
{
  "mcpServers": {
    "folio": {
      "command": "npx",
      "args": [
        "-y",
        "@jakubro/folio"
      ]
    }
  }
}
```

### Other clients (your client's MCP settings (most use this shape))

```json
{
  "mcpServers": {
    "folio": {
      "command": "npx",
      "args": [
        "-y",
        "@jakubro/folio"
      ]
    }
  }
}
```

## FAQ

### What does Folio need to run?

Node.js 22.18 or later; start it with npx @jakubro/folio and a folder path.

### Does it modify my files?

It writes into the folder only what a FOLIO.md there asks for; its own state is kept in ~/.local/state/folio.

### How do I use it from Claude Code?

Add the marketplace with claude plugin marketplace add jakubro/folio, then install folio@folio.

### What licence is it?

GNU GPL v3.

### Is Folio free?

Yes. Folio is open source, so you can use and self-host it for free.

### How do I add Folio to Claude Code?

Run this command in your terminal: claude mcp add folio -- npx -y @jakubro/folio

### What are the best alternatives to Folio?

The closest alternatives to Folio are Codebase Memory, XERJ, Claude Code Ultimate Guide, Nautilus Compass Memory and note1.

## Alternatives

- [Codebase Memory](https://ai-powered.com/mcp/codebase-memory): Codebase Memory is an open-source MCP server for knowledge and memory.
- [XERJ](https://ai-powered.com/mcp/xerj): XERJ is an open-source MCP server for knowledge and memory.
- [Claude Code Ultimate Guide](https://ai-powered.com/mcp/claude-code-ultimate-guide): Claude Code Ultimate Guide is an open-source MCP server for ai models and llm tooling.
- [Nautilus Compass Memory](https://ai-powered.com/mcp/nautilus-compass-memory): Nautilus Compass Memory is an open-source MCP server for knowledge and memory.
- [note1](https://ai-powered.com/mcp/note1): note1 is an MCP server for productivity.
- [ASTra](https://ai-powered.com/mcp/astra): ASTra is a freemium MCP server for files and documents.
- [CARTESIAN ECU](https://ai-powered.com/mcp/cartesian-ecu): CARTESIAN ECU is a paid MCP server for files and documents.
- [MedXpert 图书馆连接器（通用版）](https://ai-powered.com/mcp/medxpert): MedXpert 图书馆连接器（通用版） is an open-source MCP server for knowledge and memory.

---
Source: https://ai-powered.com/mcp/folio-2
