Guide
Gravity MCP server
The Gravity MCP server lets AI apps and agents read and change a person's Gravity notes. It's Gravity's API, and it works with any client that speaks the Model Context Protocol.
https://mcp.gravitynotes.app/mcp
| Transport | Streamable HTTP, stateless |
| Protocol versions | 2026-07-28, 2025-11-25, 2025-06-18, 2025-03-26, 2024-11-05 |
| Sign-in | OAuth 2.1 with PKCE; see auth.md |
| Price | Free with Gravity Sync, which is free during the beta |
| Registry name | app.gravitynotes/gravity |
| Server Card | mcp.gravitynotes.app/mcp/server-card |
To add it to Claude, ChatGPT, Codex or Grok, follow Connect Gravity to your AI apps. In Claude Code:
claude mcp add --transport http gravity https://mcp.gravitynotes.app/mcp
Tools
| Tool | What it does |
|---|---|
search |
Finds notes by words, the way app search does. todo: dentist filters by tag. |
fetch |
Returns one note's full text. Long notes come in 60,000-character parts. |
list_notes |
Lists notes by order, tag, state, creation date and optional words, with a cursor. |
list_tags |
Lists tags with how many notes use each. |
add_note |
Adds a note at the top, with an optional tag. A request_id makes retries safe. |
append_to_note |
Adds a paragraph to the end of a note. |
edit_note |
Replaces one exact quoted piece of a note's current text. |
rescue_note |
Moves a note back to the top and unarchives it. |
archive_note |
Moves a note to Archive. |
restore_note |
Brings a note back from Deleted Notes. |
trash_note |
Moves a note to Deleted Notes. |
upload_audio |
Returns a signed link to upload a recording of up to 100 MB. |
transcribe_audio |
Turns speech in a recording into text, in 99 languages. |
add_voice_note |
Transcribes a recording and saves it as a new note. A spoken tag ("To do, …") becomes the note's tag. |
Every tool has a title, read-only, destructive, idempotent and open-world hints, and an output schema. Nothing deletes a note permanently.
Sign-in and scopes
An unauthenticated call returns 401 with a WWW-Authenticate header pointing at the protected resource metadata. From there a client finds the authorization server metadata and registers itself with a client ID metadata document or dynamic client registration. Most MCP clients do all of this for you.
notes:readcovers searching, listing and reading.notes:writecovers every change. A read-only connection that tries a write gets a step-up challenge.offline_accessadds a refresh token.
The person approving the connection needs Gravity Sync turned on in a Gravity app, on iPhone, iPad, Mac or Android. They can disconnect any app in Gravity under Settings → Gravity Sync → AI apps.
Limits
- 120 reads and 60 writes a minute for each connected app.
- 4 MiB for one request. Send bigger recordings through
upload_audio. - Access tokens last an hour. Refresh tokens rotate and last 60 days without use.
Privacy
Notes an AI app reads go to that app's provider under their terms. Gravity keeps a record of which connected app changed which note, never the note text, for 90 days. Uploaded recordings are deleted once they're transcribed, and within two days at most. The privacy policy has the details.
More: Gravity API docs · changelog · tristan@crowlabs.co