roam-research -setup-guide

This MCP server provides a Roam Research interface tailored for Claude Desktop integration on Windows. To stabilize communication, a wrapper script named roam-mcp-wrapper.js filters out non-JSON debug output so Claude Desktop only receives the JSON-RPC messages it expects. The server is configured in Claude Desktop to launch this wrapper, which in turn starts the underlying Roam MCP logic. Ensure you supply your Roam API token and the target Roam graph name via environment variables so Claude Desktop can authenticate and operate against the correct graph.

Once running, you can use Claude Desktop to send prompts and queries to Roam through the MCP server. The wrapper ensures clean JSON-RPC communication, mitigating issues where Roam’s internal debug messages would otherwise break the protocol. If you encounter missing environment variables or JSON parse errors, verify that the env vars are correctly defined in the MCP configuration (env) and that the wrapper script path is correctly referenced in the Node command.

Prerequisites:

• Windows 11
• Node.js v18.0.0 or newer
• Access to Roam Research API and a valid API token

Installation steps:

1. Create a dedicated directory outside the project for MCP servers (for example: C:\Users<USERNAME>\mcp-servers\roam-research-mcp).
2. Place or create the wrapper script roam-mcp-wrapper.js inside that directory. This wrapper should filter RoamServer: logs and only emit valid JSON-RPC messages to stdout.
3. Create the MCP configuration in Claude Desktop (or your MCP runner) pointing to the wrapper script. Example command and environment variables are shown in mcp_config below.
4. Install Node.js if not already installed. Ensure npm or other tooling is not required for this wrapper setup.
5. Start the MCP server via Claude Desktop or your MCP runner using the provided configuration.

Note: If you plan to add more MCP servers later, consider using a dedicated directory structure such as C:\Users<USERNAME>\mcp-servers and keep each server isolated to avoid issues with package.json type settings.

Tips and common issues:

• JSON Parse Errors: Ensure the wrapper filters any non-JSON debug output (RoamServer: ...) so Claude Desktop only sees valid JSON-RPC messages.
• Environment Variables: Directly specify required environment variables in the MCP config under env to avoid .env loading issues when launching from Claude Desktop.
• Path Management: Use absolute paths to the wrapper script to prevent working directory problems on Windows.
• Future scale: This setup uses a dedicated directory outside the project to avoid ES module constraints, making it easier to manage multiple MCP servers (Notion, Obsidian, etc.).