npm package: @omnilib/mcp-server
Description: MCP server for Omnilib - allows external AI agents to interact with Omnilib desktop
Latest version: 0.1.4

# @omnilib/mcp-server

MCP (Model Context Protocol) server that exposes Omnilib desktop capabilities to external AI agents. When connected, agents like Claude Code, Cursor, or VS Code Copilot can search your project, manage dashboard widgets, compile LaTeX, execute notebooks, and more — all through Omnilib's live workspace.

## Prerequisites

- **Omnilib desktop** running with a project open
- **MCP server enabled** in Settings > AI > MCP Server
- **Node.js 18+** (for `npx`)

## Quick Setup

### Claude Code

```bash
claude mcp add omnilib -- npx -y @omnilib/mcp-server
```

### Cursor

Create `.cursor/mcp.json` in your project root:

```json
{
  "mcpServers": {
    "omnilib": {
      "command": "npx",
      "args": ["-y", "@omnilib/mcp-server"]
    }
  }
}
```

### VS Code

Create `.vscode/mcp.json` in your project root:

```json
{
  "servers": {
    "omnilib": {
      "command": "npx",
      "args": ["-y", "@omnilib/mcp-server"]
    }
  }
}
```

### Windsurf

Add to `~/.codeium/windsurf/mcp_config.json`:

```json
{
  "mcpServers": {
    "omnilib": {
      "command": "npx",
      "args": ["-y", "@omnilib/mcp-server"]
    }
  }
}
```

### OpenCode

```bash
opencode mcp add omnilib -- npx -y @omnilib/mcp-server
```

### Codex

```bash
codex mcp add omnilib -- npx -y @omnilib/mcp-server
```

### Zed

Add to Zed settings (`settings.json`):

```json
{
  "context_servers": {
    "omnilib": {
      "command": {
        "path": "npx",
        "args": ["-y", "@omnilib/mcp-server"]
      },
      "source": "custom"
    }
  }
}
```

### Windows (non-WSL)

On Windows without WSL, replace `"npx"` with `"cmd"` and prepend `"/c", "npx"` to args:

```json
{
  "mcpServers": {
    "omnilib": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@omnilib/mcp-server"]
    }
  }
}
```

## How It Works

```
AI Agent  --(stdio/MCP)-->  @omnilib/mcp-server  --(HTTP)-->  Omnilib Desktop
```

1. The Omnilib desktop app starts a local HTTP server on a random port (localhost only)
2. A discovery file is written to `~/.omnilib/mcp.json` with the port and a one-time auth token
3. When your AI agent starts, `@omnilib/mcp-server` reads the discovery file, connects to the HTTP server, and exposes Omnilib's tools over MCP stdio

All communication stays on localhost. The auth token is regenerated each time the server starts.

## Available Tools

### File Operations

| Tool | Description |
|------|-------------|
| `omnilib_write_file` | Write/create files with instant UI updates, index sync, and knowledge graph updates |
| `omnilib_edit_file` | Find-and-replace editing with the same live integrations |

> **Important:** Agents should always use these instead of built-in file tools when working in an Omnilib project. Built-in tools bypass UI updates, the search index, and the knowledge graph.

### Semantic Search

| Tool | Description |
|------|-------------|
| `omnilib_semantic_search` | Vector search across all project documents — more effective than text search for understanding content |

### LaTeX

| Tool | Description |
|------|-------------|
| `omnilib_compile_latex` | Compile `.tex` files via Tectonic, returns errors/warnings, and refreshes the PDF preview |

### Dashboard Widgets

| Tool | Description |
|------|-------------|
| `omnilib_calendar_list/create/update/delete` | Manage calendar events |
| `omnilib_todo_list/create/update/delete` | Manage todo items |
| `omnilib_notes_get/update` | Read and update notes |
| `omnilib_mermaid_list/update` | Manage Mermaid diagrams |
| `omnilib_countdown_get/update` | Manage countdown timers |
| `omnilib_quicklinks_list/create` | Manage quick-link bookmarks |
| `omnilib_reminder_list/create` | Manage reminders |
| `omnilib_email_list/get` | Read Gmail messages (read-only) |

### Project Memory

| Tool | Description |
|------|-------------|
| `omnilib_memory_query` | Query the project knowledge graph for relevant context |
| `omnilib_memory_add` | Store a new fact in project memory |
| `omnilib_memory_entities` | List known entities |
| `omnilib_memory_entity_facts` | Get all facts about a specific entity |
| `omnilib_memory_stats` | Memory system statistics |

### Academic Research

| Tool | Description |
|------|-------------|
| `omnilib_search_papers` | Search across arXiv, Semantic Scholar, PubMed, OpenAlex, and CrossRef |
| `omnilib_get_paper` | Get full details of a paper by ID |
| `omnilib_search_citations` | Find papers that cite or are cited by a given paper |
| `omnilib_get_recommendations` | Get related paper recommendations |

### Tags

| Tool | Description |
|------|-------------|
| `omnilib_tags_get` | Get tags on a file |
| `omnilib_tags_update` | Add or remove tags on a file |
| `omnilib_tags_search` | Search tags by prefix |

### Jupyter Notebooks

| Tool | Description |
|------|-------------|
| `omnilib_notebook_read_cells` | Read structured cell data from a `.ipynb` file |
| `omnilib_notebook_add_cell` | Add a code or markdown cell |
| `omnilib_notebook_modify_cell` | Edit a cell's source |
| `omnilib_notebook_start_kernel` | Start a Jupyter kernel (auto-detects best available) |
| `omnilib_notebook_stop_kernel` | Stop a running kernel |
| `omnilib_notebook_execute_cell` | Execute code and capture outputs (optionally writes back to `.ipynb`) |

## Troubleshooting

| Problem | Solution |
|---------|----------|
| `Omnilib is not running or MCP server is not enabled` | Open Omnilib desktop and enable the MCP server toggle in Settings > AI |
| `Omnilib appears to have exited (stale discovery file)` | Restart Omnilib — the previous session's discovery file was not cleaned up |
| `Authentication failed` | Restart Omnilib to regenerate the auth token |
| `Frontend did not respond within 10 seconds` | Ensure a project is open in Omnilib (dashboard tools require an active project) |
| Tools return empty/null data | Check that the relevant widget or service is active in your project dashboard |

## Security

- HTTP server binds to `127.0.0.1` only (never exposed to the network)
- Random OS-assigned port per session
- 32-byte cryptographic auth token, regenerated on each start
- Discovery file restricted to owner-only permissions (`0600` on Unix, hidden on Windows)
- Constant-time token comparison to prevent timing attacks
- 1 MB request body limit