com.foreverworksPublished by foreverworks.comv0.1.1Updated Nov 3, 2026
Search, read and write your Notion workspaces, with pages as Markdown and typed database queries.
The publisher's own server: Notion
Local MCP server that lets an assistant search, read and write several Notion workspaces, with pages as Markdown and typed database queries.
Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.
Follow the launch instructions in the repository.
Search, read and write your Notion workspaces from
your AI assistant, several through one server: pages as Markdown, databases
queried and counted by column, saved views, people, comments and files. It
creates pages, rows, columns and databases, edits properties and bodies,
comments, uploads files, and moves pages to Notion's trash (kept 30 days;
restore_page brings them back). No tool is money.
You need a Notion integration per workspace, its token in a file of its own, and your top-level pages shared with it: an integration sees only what you share. Uploads take files up to 20 MiB (5 MiB on Notion's Free plan).
[Install in VS Code] [Install in Cursor] [Download for Claude Desktop]
With Claude Code:
Claude Desktop (Settings, Developer, Edit Config) and most other clients read the same command as JSON:
Each runs the published package on Node 22.19 or newer. VS Code and the Claude Desktop bundle ask for NOTION_TOKENS_DIR as they add the server. Cursor reads it from your environment instead (${env:NOTION_TOKENS_DIR}), so set it before you start Cursor. Configuration says what it holds.
In a JSON configuration, the command is node and its one argument the full path of servers/notion/dist/index.js. To share one running copy between several clients over HTTP, see docs/deploying.md.
Over HTTP, a deployment that limits its hosts sets
MCP_EGRESS_ALLOW=api.notion.com,prod-files-secure.s3.us-west-2.amazonaws.com,s3.us-west-2.amazonaws.com:
Notion's API and the hosts its files are served from.
Each file is a workspace: notion-personal and notion-work are labelled
personal and work, and the server names the labels it found at start. A
label is lower-case letters, digits and hyphens; an empty file is skipped.
There is no default folder, so a test or a hand-run copy cannot reach a
workspace by accident. The files are re-read at most once a minute, and at
once after a refused token, so a new token needs no restart. The variables
every server shares (transport, limits, MCP_FILE_ROOTS for uploads) are in
docs/configuration.md.
For each workspace:
notion-<label> in your
tokens folder, readable by you alone (mode 0600). Do not paste it into a
chat.A personal access token works in the same file instead (made at https://www.notion.so/developers/tokens, signed in to the workspace, with the Notion API capability). It acts as you: it sees every page you see, with nothing to share, and can create private top-level pages, which an integration cannot. It expires within a year.
Ask your assistant to run Notion's health check. Per workspace, it says
whether the token is accepted, the workspace and integration names, and
whether the integration sees any page yet; if not, do step 4 above.
From a shell, node dist/index.js --health prints one NOTION: line per
workspace and exits 0 when all is well, 1 when a person has to act (a refused
token, a missing capability), and 2 for a warning (an integration that sees
nothing yet, or Notion unwell), which suits a timer.
read changes nothing; write changes something in a workspace. A tool that takes an id also takes a Notion URL, and finds the workspace itself.
test/tools.snapshot.json pins what a client lists; a diff there is a
breaking change.
health says "the integration sees no page yet", or a call answers
not_shared. Notion answers the same 404 for an id that does not exist and
a page not shared with the integration. Check the id, then share the page
(step 4 of Getting a token); sharing a top-level page
shares everything under it.
auth. The token was refused: revoked, or a personal access token past
its expiry. Put a new one in the notion-<label> file; the next call reads
it.
forbidden. The integration lacks a capability for this call. Turn it on
at https://www.notion.so/profile/integrations (step 2 of
Getting a token).
config. No token files where NOTION_TOKENS_DIR points, an unreadable
one, or one holding more than one token. For download_files, set
NOTION_OUTBOX_DIR.
input from create_page with no parent. Notion refuses a top-level page
from an integration; give a parent page, or use a personal access token. Any
other input names what to fix, and nothing changed.
outcome_unknown. An append, a find-and-replace, a new page or a comment
lost its answer; it is never resent blind. Read the page (or search for a
new one) before writing again: the change may be there.
conflict: someone edited the same object at that moment; read it again,
then retry. rate_limited: Notion still throttles after the retries (180
requests a minute on the Free plan); wait a minute. api: Notion was
unreachable or failed; retry later. With reason: "drift" its answer changed
shape: please report it.
An id lives in exactly one workspace, so src/app/locate.ts asks each until
one answers; a 404 from all is not_shared. Every id found, or revealed by a
search or query, is remembered while the process runs, so misses are paid
once. A URL may be on notion.so, notion.site or app.notion.com; ?p=
names a page open over a database.
A database is named by its own id or its data source's (search gives both).
Since API 2025-09-03 a database holds data sources, nearly always one; with
several, source names the table, and omitting it is refused with their
names.
Empty values are left out of a page or row (describe_database lists every
column). A page object lists at most 25 pages of a relation; read_page reads
the rest from the property endpoint (up to 1,000), and a query row lists such
a column under truncated. The server does no arithmetic on numbers.
whereNotion's filter keys a condition by the column's type, which agents get wrong.
where names the column, an op and a value, and takes the type from the
schema:
An op the type lacks, or an option that does not exist, is refused with what
exists, before any request. A person column takes a name, an email, a user id
or "me". A name is matched against the workspace's users, exactly first,
then as part of one person's name; one that two people share or nobody has is
refused with who fits. notion_filter takes Notion's own filter object for
what where cannot say, ANDed with it.
Search returns templates as ordinary pages, and a template shapes every
future row, so list_database_templates names them and trash_page refuses
one without allow_template. create_page with template checks it against
that database's templates. Notion fills the row right after making it, so
read_page a moment later shows the result. Properties given beside a
template are kept; a Markdown body is refused, since it would race the
template's.
add_column, add_options and create_database check the request against
the table as it is, before sending: a name already taken, an option already
there, a setting the type lacks, a formula without its expression, a relation
without its target, more than Notion's 100 options. Notion documents a schema
update's option list as the options to set, so add_options sends back every
current option by id, then the new ones, and reads the column back: an option
that went missing fails the call.
upload_file takes a file by path inside MCP_FILE_ROOTS, or as base64 with
its SHA-256 from a script, never as text a model types. In a row's files
column it joins the files there; otherwise it becomes a block at the end of
the body (an image, a PDF, a video or a sound, by its type). Notion's API
replaces a files column whole and cannot write back a file it hosts, so a
column holding Notion-hosted files needs replace: true, which lets them go;
external links are always kept.
download_files saves a page's Notion-hosted files to NOTION_OUTBOX_DIR:
its files columns and the file, image, PDF, video and audio blocks of its
body, nested ones included (the first 1,000 blocks). Notion's links are signed
URLs valid for an hour, fetched over https without the workspace's token or
following redirects. External links are listed, never fetched, since they can
point anywhere.
query_view runs a view as Notion does, quick filters and me included.
Notion answers with page ids only and keeps the result about 15 minutes, so
query_view reads each row itself (25 by default, up to 100 a call), and
nextCursor reads on in the same result. Once that result expires, the tool
says to start again; a row trashed or unshared meanwhile is listed under
unreadable.
On an AI meeting-notes page, read_page with include_transcript answers the
summary, notes and transcript as one Markdown text. read_blocks names the
blocks behind them, and on transcriptBlockId reads the transcript line by
line, each with the block id an AI summary's citations link to.
replace_content cannot be undone through the API, and a model slips on both
its arguments: a page id from the wrong row, or a markdown that came out
empty. So an empty body needs clear: true, and the answer gives the page's
title with blocksBefore and blocksAfter, so a wrong page or a body that
shrank to almost nothing shows at once.
2026-03-11 in every request: the one with the Markdown
endpoints and in_trash.Retry-After.conflict_error proves nothing happened,
so every request repeats. A 5xx or a lost connection proves nothing either
way: reads repeat, and so does whatever lands the same twice (a property
update, a move, a whole-body replace); the rest fail as outcome_unknown
(notionApi.ts marks which is which). A 401 is retried once, after the
token file is read again.Notion scopes every token to one workspace, the hosted MCP's included, so no single sign-in reaches several. The hosted MCP's data-source query depends on the plan, it relays tools this repository does not model, and its refresh token can die and need a person. A personal access token also acts as the user, over REST, for a renewal once a year.
scripts/smoke.ts drives the built server read-only, or writes and trashes
one page with --write.
paragraph blocks of text (API 2026-03-11, @notionhq/client
5.27.0, whose types have no speaker field), though Notion's app shows
speaker turns and timestamps.query_database answers at most 1,000 rows a call (then nextCursor),
and count_rows reads at most Notion's 10,000 per query.replace: true, or the file goes into the body.Searched 2026-10-15; Notion's MCP page re-read 2026-10-18.
mcp.notion.com, Streamable HTTP) needs an
OAuth sign-in in a browser and reaches one workspace per connection; only
Enterprise workspaces can sign in without a browser, through their identity
provider. Its tool set is the widest (views, file uploads, SQL over data
sources, Custom Agent sessions). AI search and unlimited SQL over data
sources need a Business or Enterprise plan with Notion AI; querying a saved
view works on every plan.@notionhq/notion-mcp-server, Notion's open-source server (stdio or
HTTP, one token in an environment variable), is no longer actively
maintained.notion-mcp-server on npm, the strongest community server: stdio or
HTTP on one token, three tools over 47 operations, typed filters and writes
checked against the database's schema, templates, views, file uploads and
batched writes.@suekou/mcp-notion-server (stdio, one token) also queries and creates
rows from the schema.notion-multi-workspace, the only multi-workspace server found, is
archived.This one exists for several workspaces behind one headless server, each with its own token file: search covers them all at once, and any page or database id or URL finds its own workspace. It also counts matching rows, per value of a column, without sending them, and its whole-body replace refuses an empty body unless asked and answers with the block counts before and after.
Source: servers/notion/README.md at commit cbd1121
Add a column
Add a column to a database: a name it does not have yet, a type, and that type's settings (options, a number's format, a formula's expression, a relation's target). Checked against the table as it is now before anything is sent; answers the column as Notion made it. Renaming and deleting columns are left to Notion's app.
columnrequiredsourceaccountdatabaserequiredAdd a comment
A comment on a page, or a reply in one of its discussions, shown in Notion as the workspace's integration. Not resent after a lost answer (outcome_unknown): get_comments says whether it arrived.
pagerequiredaccountmarkdownrequireddiscussionAdd options to a column
Add options to a select, multi-select or status column (a status option in a group: To-do, In progress, Complete). The options already there are kept and sent back by id, and the column is read back after: an option that went missing fails the call. Names already there are skipped and listed under alreadyThere. For one new option while writing a row, create_page's allow_new_options is enough.
groupcolumnrequiredsourceaccountoptionsrequireddatabaserequiredAdd to a page
Markdown added to a page's body: at the end (default), at the start, or after a passage. Not resent after a lost answer: that is outcome_unknown, and read_page says whether it went through.
atpagerequiredafteraccountmarkdownrequiredCount rows
How many rows match where, and with by, how many hold each value of one column ("how many tasks per status"), most first; an empty value counts as "(empty)", and a multi-select row counts once per option. Reads the matching rows without sending them, up to Notion's 10,000 per query.
bymatchwheresourceaccountdatabaserequiredin_trashnotion_filterCreate a database
Create a database under a page, with a title column and the other columns given, each checked against the others before anything is made (and a relation's target found in the same workspace). Answers its id, URL and table. A database is not created twice: if the answer is lost it is outcome_unknown, and search says whether it exists.
titlerequiredinlineparentrequiredaccountcolumnstitle_columnCreate a page
A new row in a database, its properties checked against the columns first (an unknown column or option is refused with the ones that exist), a child page under a page, or with no parent a private page at the top of a workspace (a title and a body, no properties). The body is Notion's Markdown. A row can start from one of its database's templates (template): Notion applies it just after the page is made, so read_page a moment later shows what it filled in. Answers the new page's workspace, id and URL. A page is not created twice: if the answer is lost it is outcome_unknown, and search or query_database says whether it exists.
icontitleparentsourceaccountmarkdowntemplatepropertiesallow_new_optionsDescribe a database
A database's columns: name, type, the options of a select, multi-select or status (with a status's groups), where a relation points, a formula's expression. Read it before writing where, sort or properties: every one of those names these columns. A database holding several tables (data sources) lists each.
accountdatabaserequiredDownload a page's files
Save the files Notion hosts for a page to this server's outbox: its files columns and the file blocks of its body (up to 50 MiB each). Answers each file's path, size and SHA-256, and where it was on the page. External links are listed, not fetched. A file that fails is listed with why, beside the others.
bodypagerequiredcolumnaccountsave_dirEdit a page
Find and replace in a page's body, in its Markdown as read_page shows it. The smallest change that does the job: the rest of the page, its comments and its history stay as they were. Not resent after a lost answer: that is outcome_unknown, and read_page says whether it went through.
pagerequirededitsrequiredaccountallow_deletingGet comments
The open comments on a page, oldest first, each with its discussion, author, time and text. Resolved ones are not listed by Notion.
pagerequiredlimitcursoraccountHealth
Ask each workspace: is its integration token accepted, which workspace and integration it is, and whether it sees any page at all (a new integration sees nothing until pages are shared with it). One broken workspace never hides the others' answers. Run this before concluding the server is broken.
accountList accounts
The Notion workspaces this server reaches, by label (one per token file), from the token files alone: no request to Notion. Every other tool finds an id's workspace by itself, so a label is needed only to narrow a search. Says nothing about whether a token works; that is health.
Takes no parameters.
List database templates
The page templates of a database or data source, with their page ids, names and default flags. Use this catalog to distinguish templates from ordinary rows; search can return both. Inspect their pages before editing recurring content. Follow nextCursor when hasMore is true.
limitcursorsourceaccountdatabaserequiredList users
The people (and bots) of every workspace, or of the one account names: each one's id, name, and email when the token may read it. A person column's where takes a name or an email directly, so this is for checking who is who, or for the id when two people share a name.
queryaccountList a database's views
A database's saved views (table, board, calendar, ...): each one's id, name, type, the table it shows, and the filter and sorts saved in it, in Notion's query grammar with columns by name. Use it to find the view a person means ("my Open tasks"), then query_view to read its rows exactly as Notion shows them.
sourceaccountdatabaserequiredMove a page
Under another page, or into a database as a row. Only within the page's own workspace: Notion cannot move a page between workspaces.
torequiredpagerequiredsourceaccountQuery a database
Rows of a database, filtered by where (checked against the columns first), sorted, with the columns asked for. Each row is its id, its title and its non-empty columns as plain values. A relation lists its first 25 pages here (truncated names it); read_page lists them all. nextCursor reads on; Notion stops one query at 10,000 rows (incomplete says so). Works on the Free plan, unlike the hosted connector's SQL query.
sortlimitmatchwherecursorsourceaccountdatabaserequiredin_trashpropertiesnotion_filterQuery a saved view
The rows a saved view shows, in its order, filtered and sorted exactly as Notion applies the view (quick filters and 'me' included), with total, the number of rows the view holds. Each row is its id, title and non-empty columns as query_database answers them. Notion keeps a view's result about 15 minutes: nextCursor reads on in that same result, and after that a new call without cursor starts again. A view takes no extra filter: for that, query_database with where.
viewrequiredlimitcursoraccountpropertiesRead blocks
The blocks directly inside a page or a block, in order, one level down: each one's id, type and plain text, and hasChildren when it holds more (read those by its id). An AI meeting-notes block answers its title, status, recording and calendar times, and the ids of the blocks that hold its summary, notes and transcript, each readable here in turn. A type the API does not support says its Notion name under unsupported. For a page's body as one text, read_page is cheaper.
blockrequiredlimitcursoraccountRead a page
One page by id or URL, in whichever workspace has it: its title, parent and properties as plain values (a select is its option's name, a relation its page ids, all of them), and its body as Notion's Markdown. Empty properties are left out. A body past Notion's limit (~20,000 blocks) comes back cut, with contentTruncated and the ids of the parts left out, each readable as a page. A database's id is refused: use describe_database.
pagerequiredaccountcontentinclude_transcriptReplace a page's body
A page's whole body, replaced by this Markdown. Properties are untouched. Child pages and databases in the body are kept unless allow_deleting. An empty body needs clear: true. Answers with the page's title and how many blocks its body held before and after; check both. Prefer edit_content for a change to part of a page.
pagerequiredclearaccountmarkdownrequiredallow_deletingRestore a page
Out of Notion's trash, back where it was. Notion's API cannot restore a page from the top level of a workspace (it answers a validation error); that one is restored from the Trash in Notion.
pagerequiredaccountSearch
Pages and databases by title, in every workspace at once unless account names one. Notion matches words in titles, not in page bodies. Each hit says its workspace, kind, id and parent; a database hit also carries the dataSourceId of its table. Only what is shared with the workspace's integration can be found. A workspace that fails is listed under failed, beside the others' hits.
kindlimitquerycursoraccountTrash a page
Into Notion's trash, with everything under it. Direct deletion of database templates is refused unless allow_template is explicit. Notion keeps trash 30 days; restore_page brings it back.
pagerequiredaccountallow_templateUpdate a page
Change a page's properties (a row's columns, checked against the database's schema; a page's title as properties: {title: ...}) and its icon. Only the columns named change. Answers the page as read_page does, without the body. The body is changed with append_content, edit_content and replace_content.
iconpagerequiredaccountpropertiesallow_new_optionsUpload a file to a page
Upload a file to Notion and attach it to a page: to one of a row's files columns, or as a block at the end of the page's body (an image, PDF, video or sound shows as such). The file goes by path, never as text you type. Answers with its size and SHA-256 as sent: compare them with the source. A column's own Notion-hosted files are kept unless the API cannot write them back, which is refused unless replace says so; nothing is uploaded before every check passes.
filerequirednamepagerequiredcolumnaccountreplace90% of the applicable checks met
How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.
Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.
com.notionOfficial publisher
Notion's hosted MCP server, published by notion.com; credential required; Streamable HTTP.
Published by GitHub account shoubhiksaha
Local MCP server that uploads large files from disk (up to 5 GB) to Notion and attaches them to pages or blocks.
com.insightfulpipe
Hosted Notion MCP server that lets an AI assistant search, read and, with write scopes, create or update Notion pages, databases, data sources and blocks.
Published by GitHub account imgul
Local MCP server for the Notion Arena component registry, letting an assistant search, inspect and plan installation of Notion widgets and recipes.
Published by GitHub account shck-dev
Lets an assistant search a Notion workspace and export, import, append, and create pages as markdown, plus manage comments and images.
claude mcp add notion -e NOTION_TOKENS_DIR="<path to Notion tokens folder>" -- npx -y @foreverworks/mcp-notion{ "mcpServers": { "notion": { "command": "npx", "args": ["-y", "@foreverworks/mcp-notion"], "env": { "NOTION_TOKENS_DIR": "<path to Notion tokens folder>" } } }}git clone https://github.com/foreverworks/mcps.git && cd mcpsnpm ci && npm run buildclaude mcp add notion -e NOTION_TOKENS_DIR="<path to Notion tokens folder>" -- node "$PWD/servers/notion/dist/index.js"{"where": [{"property": "Status", "op": "equals", "value": ["In progress", "Blocked"]}, {"property": "Due", "op": "next_week"}], "match": "all"}