Claude Mongodb

MongoDB Claude Protocol Examples License

The thing this fixes

Claude has no memory between conversations. Everything you established in a chat — the notes you pasted, the structure you agreed on, the fifty items it extracted from a PDF — is gone when the window closes. Projects and files help, but they are documents you re-read, not data you query. You cannot ask a file "which of these did I mark as difficult, sorted by when I last saw them."

A document database fixes that in the least clever way possible: Claude writes JSON-ish documents into MongoDB and reads them back later. No embeddings, no retrieval pipeline, no framework. It is just storage that happens to be reachable from inside a conversation.

This repository is a working setup for that, using a hosted MongoDB 7 instance from freebase.cloud and its MCP endpoint. The worked example is a language-learning vocabulary store, because vocabulary is exactly the sort of thing that is worthless in a chat log and useful in a collection.

What it looks like in practice

Illustrative, not a recorded session — the shape is right, your data will not be:

Monday. You: I'm reading a German article. New words: der Vorwand (pretext), beharren auf (to insist on), zwangsläufig (inevitably). Save them with the source and mark all three as unfamiliar.

Claude: (calls notebook_store) Stored three entries in vocab with source: "Zeit article, 2026-08-17" and confidence: 1.

Thursday, new conversation, nothing carried over. You: Quiz me on the German words I've seen in the last two weeks that I'm still shaky on.

Claude: (calls notebook_query) Eleven entries with confidence <= 2. Starting with the three from Monday's article — what does beharren auf mean, and which case does it take?

You: Dative? And it means to insist on something.

Claude: Accusative, actually — beharren auf takes the accusative when it means insisting on a position. Marking that one as still weak and bumping the other two. (calls notebook_store with mode: "append" on a reviews collection)

The second conversation knew nothing about the first except what was in the database. That is the whole trick.

Setup

Sign up on the freebase.cloud dashboard, create a session, choose MongoDB. Then Settings → MCP → New Token, pick the connection, copy the URL. It has this shape:

https://freebase.cloud/api/mcp/YOUR_TOKEN

The token is a path segment rather than a header, so any client that accepts a URL can use it. Guard it like a password — it is read and write access to the database.

Claude Desktop. Settings (⌘, / Ctrl+,) → Connectors — recent builds put this under Customize → Connectors — then Add custom connector, paste the URL, Add. Switch it on inside a conversation with the + button in the composer. On the Free plan you get one custom connector at a time. Note that claude_desktop_config.json cannot hold a remote HTTP server; the UI is the supported route, and mcp-remote is the workaround if you need a file. The same steps with the MongoDB specifics spelled out are in the Claude connection walkthrough.

Claude Code.

claude mcp add --transport http notebook https://freebase.cloud/api/mcp/YOUR_TOKEN

Add --scope project to write a committable .mcp.json. If you write that file yourself, include "type": "http" — an entry with a bare url and no type fails to load.

Both clients can point at the same connection simultaneously.

Designing collections a model will get right

MongoDB's flexibility is a liability here. A model writing free-form documents will invent difficulty, level, and confidence across three conversations and then be unable to query any of them. Two things prevent that.

Decide the shape once, in the database

{
  term:       "beharren auf",
  lemma:      "beharren",
  language:   "de",
  gloss:      "to insist on",
  register:   "neutral",
  grammar:    { pos: "verb", separable: false, governs: "accusative" },
  confidence: 1,                       // 1 unfamiliar .. 5 solid
  tags:       ["reading", "zeit"],
  source:     "Zeit article, 2026-08-17",
  first_seen: ISODate("2026-08-17"),
  last_seen:  ISODate("2026-08-17")
}

Nested documents and arrays are fine — the aggregation pipeline reaches into them with $unwind and dotted paths. What is not fine is the same concept spelled three ways.

Write it down where the model will read it

notebook_annotate_table attaches a description to a collection. It persists server-side and is returned by notebook_list_tables on every reconnect, so it functions as a schema note that survives the conversation:

Annotate the vocab collection: one document per term per language. confidence runs 1-5 where 1 is
unfamiliar; never write "difficulty" or "level". grammar.governs applies to verbs and prepositions
only. Review outcomes belong in the reviews collection, not here.

The negative clauses do more work than the positive ones. examples/annotate.sh sends exactly this kind of annotation for three collections in one pass.

Repository layout

examples/
  vocab_store.py       PyMongo — insert terms, mark reviews, print a due list
  review_queue.mjs     Node driver — aggregation pipeline that builds the study queue
  annotate.sh          curl against the MCP endpoint; annotates the collections
  README.md            environment variables and run order

vocab_store.py and review_queue.mjs connect over MongoDB's native wire protocol; annotate.sh speaks MCP. Same database, two doors.

Two ways in

MongoDB is one of the three engines on freebase.cloud that expose a real TCP wire protocol, so alongside MCP you get:

mongosh "mongodb://HOST:27017/mydb"

Mongoose, PyMongo, Motor and the native Node driver connect unmodified — including population, virtuals and middleware — and mongodump / mongorestore work over the same connection. This matters more than it sounds: it means an assistant-written collection is not trapped inside an assistant. Your application reads it, your scripts back it up, you can leave whenever you want.

The instance runs MongoDB 7.0.4, so the 7.0 aggregation stages, multi-document transactions, JSON Schema validators and time-series collections behave as the manual describes.

Where this approach stops working

• It is not semantic search. Queries are $match and $regex, not similarity. If you need "find the note that is about declension", this is the wrong tool by itself.
• Result size is context size. Ten thousand documents returned is ten thousand documents in the window. Push filtering and grouping into the aggregation pipeline.
• The model can be wrong about your data. It writes what it inferred from the conversation. For anything that matters, read it back and check before building on it.
• Free tier scope. Development, prototyping and small production workloads. Nothing here claims quotas, backup schedules or availability figures — check the dashboard for what applies to you.
• Token scope. One MCP URL, full access. Use a separate connection for data you would not want overwritten.

Tool reference

Four tools, prefixed with your connection name. These are the arguments they take:

Tool	Arguments	Notes
notebook_query	query	A MongoDB JSON query. Returns matching documents.
notebook_store	table, rows (array of objects), mode	mode is append (default) or replace. table is the collection.
notebook_list_tables	none	Collections, field names, document counts, stored annotations.
notebook_annotate_table	table, description, format	format may carry structure, sample, key_pattern, ttl.

Pick a connection name that reads well in a sentence — you choose it when you create the connection, the model uses these names in its narration, and notebook_query is easier to follow than db1_query.

Related

• Free MongoDB cloud instance
• How to connect Claude to MongoDB
• freebase.cloud
• MongoDB 7.0 manual
• Model Context Protocol

Contributions welcome — especially better annotation text. Getting a model to keep a schema stable is more prompt engineering than database engineering, and this repo does not have it solved.

Released under the MIT License.

freebase.cloud is an independent service and is not affiliated with MongoDB, Inc. or Anthropic, PBC.