Ultrahuman MCP

Chat with your Ultrahuman Ring data in Claude, ChatGPT, Cursor, or any other AI app that supports MCP ("Model Context Protocol", the standard way to plug tools into AI apps).

Once it's connected, you can ask things like:

• "How did I sleep last night?"

• "Compare my HRV and resting heart rate over the last 7 days."

• "Was my recovery better on the days I walked more?"

• "What was my average glucose yesterday?" (if you wear a glucose monitor)

The AI only reads your data. Nothing gets changed.

What it can see

Heart rate and similar data come as hundreds of readings a day. By default the server turns those into a short summary (min, max, average) so your chat doesn't get flooded. Ask for "full detail" if you want every reading.

Related MCP server: Oura Ring MCP Server

1. Get your Ultrahuman key

You only need one of these.

Option A: Personal API token (easiest, recommended)

1. Go to https://vision.ultrahuman.com/developer-docs and log in with your Ultrahuman account.

2. Create a Personal API token and copy it.

Option B: OAuth app (the Partner API)

"OAuth" is the sign-in-with-Ultrahuman flow: you approve the app once in your browser instead of pasting a token. Use this if you already have an Ultrahuman partner app, or want the profile tool.

1. In the same developer portal, create an OAuth app. Copy its Client ID and Client Secret.

2. Set its Redirect URI to https://YOUR-APP.up.railway.app/callback. You'll get this address in step 2 below, and it has to match exactly.

2. Put it on Railway

1. Push this repo to your GitHub (or fork it).

2. On Railway: New Project → Deploy from GitHub repo → pick this repo. The first deploy will fail because nothing is set up yet. That's expected.

3. Open the service and go to Settings → Networking → Generate Domain. You'll get something like https://ultrahuman-mcp-production.up.railway.app.

4. Go to Variables and add:

   Variable	Value
   ULTRAHUMAN_API_TOKEN	Your personal token (option A)
   MCP_API_KEY	A long random password you make up. This keeps strangers out of your data. Create one with openssl rand -hex 32
   TZ	Your timezone, e.g. Asia/Kolkata or America/New_York, so "today" means your today

   For option B, skip ULTRAHUMAN_API_TOKEN and add these instead:

   Variable	Value
   ULTRAHUMAN_CLIENT_ID	From your OAuth app
   ULTRAHUMAN_CLIENT_SECRET	From your OAuth app

   Then give the service a Volume (right-click the service → Attach Volume, any mount path such as /data). A volume is a small disk that survives restarts, so you stay logged in. The server finds it by itself.

   Railway redeploys after you save the variables.

5. Open your address in your browser. You should see "connected": true (option A).

Option B only: open https://YOUR-APP.up.railway.app/login?key=YOUR_MCP_API_KEY once, sign in to Ultrahuman, and approve. After that, "connected" will show true. The server keeps itself logged in from then on.

Your MCP address is:

https://YOUR-APP.up.railway.app/mcp

3. Connect your AI app

In each example below, replace YOUR-APP and YOUR_MCP_API_KEY with your own values.

Claude (claude.ai web, desktop, mobile)

Settings → Connectors → Add custom connector

• Name: Ultrahuman

• URL: https://YOUR-APP.up.railway.app/mcp?key=YOUR_MCP_API_KEY

The connector screen only takes a URL, so the key goes at the end of it. Keep this URL private.

Claude Code

claude mcp add --transport http ultrahuman https://YOUR-APP.up.railway.app/mcp \
  --header "Authorization: Bearer YOUR_MCP_API_KEY"

Cursor, Windsurf, VS Code, and other apps

Most apps take a config like this:

{
  "mcpServers": {
    "ultrahuman": {
      "url": "https://YOUR-APP.up.railway.app/mcp",
      "headers": { "Authorization": "Bearer YOUR_MCP_API_KEY" }
    }
  }
}

If an app doesn't let you add headers, use the ?key=YOUR_MCP_API_KEY URL from the Claude section.

ChatGPT

Turn on developer mode in ChatGPT's settings, then add a custom connector using the ?key= URL from the Claude section.

Running it on your own computer (no hosting)

Needs Node.js 20 or newer.

git clone https://github.com/ameeetgaikwad/ultrahuman-mcp.git
cd ultrahuman-mcp
npm install

Then add it to Claude Desktop's config file (Settings → Developer → Edit Config):

{
  "mcpServers": {
    "ultrahuman": {
      "command": "node",
      "args": ["/full/path/to/ultrahuman-mcp/src/index.js", "--stdio"],
      "env": { "ULTRAHUMAN_API_TOKEN": "your-token-here" }
    }
  }
}

Restart Claude Desktop and you're done. You don't need MCP_API_KEY here because nothing goes on the internet. If Claude Desktop says it can't find node, replace "node" with the full path you get from which node (Mac/Linux) or where node (Windows).

To run the web version locally instead: copy .env.example to .env, fill it in, and run node --env-file=.env src/index.js.

Troubleshooting

• "Wrong or missing MCP_API_KEY": the key in your AI app doesn't match the MCP_API_KEY on Railway.

• "Incorrect Personal API Token": the Ultrahuman token is wrong or was deleted. Make a new one.

• "Not connected to Ultrahuman yet" (option B): open /login?key=... again. If this keeps happening after restarts, check that the service has a volume attached.

• Redirect URI error on the Ultrahuman login page (option B): the Redirect URI in your OAuth app must be exactly https://YOUR-APP.up.railway.app/callback. Also make sure you generated the Railway domain before the last deploy; if not, redeploy once (Deployments → ⋮ → Redeploy).

• Empty data for a day: the ring may not have synced yet. Open the Ultrahuman app to sync.

Good to know

• Ultrahuman also runs its own official MCP server at https://api.ultrahuman.com/mcp. This project is a small one you host and control yourself, built on their public API.

• Anyone who has your MCP_API_KEY (or the ?key= URL) can read your health data. Treat it like a password. If it leaks, change it on Railway.

• Health data from this tool is for your own insight, not medical advice.

Files

src/index.js       starts the server (web or local mode)
src/tools.js       the tools the AI can use
src/ultrahuman.js  talks to the Ultrahuman API

Run npm test to check that it works.

MIT license.