# Workfile MCP server

> Lets an AI client manage project work, documentation, history, and durable memory using repository-native Markdown files.

- Repository: https://github.com/illodev/workfile
- Page: https://hostedmcp.org/servers/illodev/workfile
- Transport: stdio
- Stars: 3
- License: MIT
- Latest version: 0.13.2

## Install

### Claude Code

```sh
claude mcp add workfile -- npx -y @illodev/workfile
```

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

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

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

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

### VS Code CLI

```sh
code --add-mcp '{"name":"workfile","type":"stdio","command":"npx","args":["-y","@illodev/workfile"]}'
```

### Claude Desktop (`claude_desktop_config.json`)

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

### Codex

```sh
codex mcp add workfile -- npx -y @illodev/workfile
```

### Codex config.toml (`~/.codex/config.toml`)

```toml
[mcp_servers.workfile]
command = "npx"
args = ["-y", "@illodev/workfile"]
```

### Gemini CLI

```sh
gemini mcp add -s user workfile npx -- -y @illodev/workfile
```

### Gemini settings.json (`~/.gemini/settings.json`)

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

## FAQ

### What is the core principle of Workfile?

The repository is the database, meaning all work, docs, and memory are stored as canonical Markdown files within the repository.

### Does Workfile store data in a separate database?

No, it uses the repository itself for storage, ensuring no exclusive state is kept in a browser or a database.

### How does Workfile handle project memory?

It uses typed, atomic, and lifecycle-aware records organized into collections like learnings, decisions, incidents, conventions, and context.

### Can I use Workfile with existing agents?

Yes, it is designed to compose with agents by syncing its protocol into the instruction files an agent already reads.