roam-sdk 0.4.0

Roam Research SDK and terminal UI client
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99

# MCP Setup

## Configuration

The MCP server needs your Roam graph name and API token. Configure via environment variables or config file.

### Environment variables

```bash
export ROAM_GRAPH_NAME="your-graph-name"
export ROAM_GRAPH_API__TOKEN="roam-graph-token-..."
```

### Config file

Same config file as the TUI (`~/.config/roam-tui/config.toml`):

```toml
[graph]
name = "your-graph-name"
api_token = "roam-graph-token-..."
```

## Client configuration

### Claude Desktop / Claude Code

Add to your MCP settings:

```json
{
  "mcpServers": {
    "roam": {
      "command": "npx",
      "args": ["-y", "roam-tui@latest", "--mcp"],
      "env": {
        "ROAM_GRAPH_NAME": "your-graph-name",
        "ROAM_GRAPH_API__TOKEN": "roam-graph-token-..."
      }
    }
  }
}
```

### Using a local binary

If you installed via `cargo install roam-sdk`:

```json
{
  "mcpServers": {
    "roam": {
      "command": "roam",
      "args": ["--mcp"],
      "env": {
        "ROAM_GRAPH_NAME": "your-graph-name",
        "ROAM_GRAPH_API__TOKEN": "roam-graph-token-..."
      }
    }
  }
}
```

### Cursor

Add to `.cursor/mcp.json` in your project or `~/.cursor/mcp.json` globally:

```json
{
  "mcpServers": {
    "roam": {
      "command": "npx",
      "args": ["-y", "roam-tui@latest", "--mcp"],
      "env": {
        "ROAM_GRAPH_NAME": "your-graph-name",
        "ROAM_GRAPH_API__TOKEN": "roam-graph-token-..."
      }
    }
  }
}
```

## Supported platforms

The npm package includes pre-built binaries for:

| Platform | Architecture |
|----------|-------------|
| macOS | ARM64 (Apple Silicon), x86_64 |
| Linux | x86_64, ARM64 |
| Windows | x86_64 |

## Verifying

Once configured, ask your AI assistant to search your Roam graph:

> "Search my Roam graph for pages about 'project'"

It should use the `search` tool and return matching page titles.