← All integrations

Roam HQ MCP server

12 operations0 webhooks

Virtual office with Roam HQ - read the token's own identity, directory users, chats, groups and meetings, read a chat history and a meeting transcript, and post or edit a message and add a reaction.

Use Roam HQ in Claude, ChatGPT, Cursor or another MCP client

Connect Roam HQ once in Corsair, then add one MCP address to your agent.

Connect Roam HQ
Setup steps for Claude, ChatGPT, Cursor and Claude Code

Building your own app on the Corsair SDK? Get API keys

Try Roam HQ with your agent

Connect Roam HQ, then paste this into Claude, ChatGPT or Cursor. For ideas from other apps, see the use cases.

Using Corsair, show me what you can do in Roam HQ on my account, then run one read-only example and show me the result.

Runs once, when you ask

Roam HQ tools and triggers

Tools are what your agent can do in Roam HQ through Corsair's MCP server. Triggers are the Roam HQ events a routine can start from.

Chat

  • HistoryRead-only

    Read a chat or group’s messages with time-window and thread filters plus cursor paging

    chat.history

  • ListRead-only

    List the chats the token can see, with cursor paging

    chat.list

  • PostWrite

    Post a message to a chat, group or direct conversation, or schedule one for later

    chat.post

  • UpdateWrite

    Edit a message the token posted, replacing its content

    chat.update

Meetings

  • ListRead-only

    List meetings with a time window, plus cursor paging

    meetings.list

  • TranscriptRead-only

    Fetch a meeting’s transcript cues with their speaker id and timing

    meetings.transcript

Reactions

  • AddWrite

    Add an emoji reaction to a message

    reactions.add

  • ListRead-only

    List the reactions on a message, and the votes on each option when it is a poll

    reactions.list

Users

  • InfoRead-only

    Look up one person or bot by uuid or email, including their role and availability

    users.info

  • ListRead-only

    List directory members with a search phrase or an explicit id list, plus cursor paging

    users.list

Groups

  • ListRead-only

    List groups with a search phrase and type filter, plus cursor paging

    groups.list

Token

  • InfoRead-only

    Read the account behind the token: its user, bot, workspace and granted scopes

    token.info

Connect Roam HQ to Claude, ChatGPT or Cursor

  1. 1

    Connect Roam HQ in Corsair

    Add your Roam HQ API key once in Corsair. Corsair stores the credential encrypted and makes the Roam HQ API calls for your agent, so it never goes into a prompt or a config file. Connect Roam HQ

    If your link lets the agent add apps, you can skip this: it gives you a sign-in link the first time it needs Roam HQ. On a ChatGPT personal plan, connect Roam HQ here first.

  2. 2

    Add Corsair's MCP server to your agent

    Every client uses the same address:

    https://mcp.corsair.dev/mcp
    Open Customize → Connectors → Add custom connector, paste the address, then select Connect.

    Codex, Gemini CLI, VS Code, Zed and other clients with OAuth sign-in work the same way. Clients without it, such as GitHub Copilot's coding agent, use a link's own address and an API key. Setup for every client

  3. 3

    Sign in and choose what needs your approval

    Your client opens Corsair to sign in. Pick a link: the apps your agent can use and a mode that decides what it may do without asking. None of Roam HQ's operations are destructive, so in the default Cautious mode they all run right away. Strict mode asks before each of its 3 writes, and Read mode allows reads only.

FAQ

Install corsair and @corsair-dev/roam, add the Roam HQ plugin, and connect with an API key. Then call methods like corsair.roam.api.chat.history() from your app. Corsair keeps each tenant isolated.

Yes. Roam HQ requires an API key from your Roam HQ account or developer dashboard. Create credentials with access that matches what you automate, then paste them into Corsair or connect through managed auth in Hub.

Yes. One Corsair client can hit Roam HQ, GitHub, Notion, Stripe, and the rest. Trigger Roam HQ from a webhook, push updates to Slack, or chain actions across plugins. Same tenant context across integrations, plain TypeScript.

Teams use Corsair for virtual office with Roam HQ - read the token's own identity, directory users, chats, groups and meetings, read a chat history and a meeting transcript, and post or edit a message and add a reaction. Common builds include sync jobs, admin tooling, and agents that call Roam HQ APIs from your backend.

The SDK is open source. Self-host and you pay Corsair nothing for the integration layer. Hub bills for hosted auth and execution, not per Roam HQ API call. Hub has a generous free tier. For hobby projects you can probably run the whole thing on free. Paid plans start to matter with more tenants or heavier traffic.

We maintain @corsair-dev/roam in the open repo. When Roam HQ ships API changes, upgrade the package. Your call sites stay typed. You should not need to rewrite the integration layer each time.

No. Corsair does not read your Roam HQ data or hold individual access credentials. Credentials stay in your database. API calls run on your instance. We do not store Roam HQ data on your behalf.

Yes. Add https://mcp.corsair.dev/mcp as a custom connector or MCP server in Claude, ChatGPT, Cursor, VS Code, Claude Code, Codex or any client that supports remote MCP servers with OAuth sign-in, then sign in to Corsair. On ChatGPT personal plans, custom servers currently get read tools only.

Yes. Put Roam HQ on a link in Strict mode and every write waits for your approval, while destructive actions are refused. None of the Roam HQ operations are destructive, so the default Cautious mode runs them all without asking. You can change a link's mode at hub.corsair.dev/me.