agentleFS
ai-analyst-labai-analyst-lab/ai-analyst/.claude/skills/setup-notion/SKILL.md

setup-notion

Skill304 starsChanged 2 months agoMITView on GitHub

Connect Claude Code to Notion's official hosted MCP, complete OAuth, verify the intended workspace with a read, and stop before any write. Use when the user asks to connect Notion, set up Notion, export to Notion, or diagnose an unavailable Notion connection.

1 other project uses a version of this.

Adopted by

Most recently taken up by

The file

Show its rules and text

We split this skill into the rules it gives an agent

17 rules. About 0 are common, 14 are distinctive, and 3 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈14

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 3

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Read .mcp.json if it exists.

    line 31
  2. Distinctive:

    Check whether a Notion server already points to the official endpoint.

    line 33
  3. Distinctive:

    If Notion tools are already available, skip configuration and verify the connection.

    line 34
  4. Distinctive:

    Before editing anything, show the user the exact non-secret change and ask for approval.

    line 35
  5. Distinctive:

    Never replace the entire MCP configuration merely to add Notion.

    line 37
  6. Very specific:

    After approval, add this project-local server entry while preserving the rest of .mcp.json:

    line 41
  7. Distinctive:

    Do not put tokens or credentials in the configuration.

    line 58
  8. Very specific:

    If this session did not load the new server, tell the user to restart Claude Code.

    line 62
  9. Distinctive:

    Before the user authorizes access, remind them to confirm:

    line 65
  10. Distinctive:

    Do not claim that OAuth proves the destination or makes every future action safe.

    line 72
  11. Distinctive:

    Ask the user for the title of a page they expect in the approved workspace.

    line 76
  12. Distinctive:

    Use only Notion's official hosted endpoint unless the user explicitly requests another server.

    line 97
  13. Distinctive:

    Stop for approval before editing MCP configuration.

    line 99
  14. Distinctive:

    Never request or store a Notion API key for this OAuth path.

    line 100
  15. Distinctive:

    Verify the workspace with a read before any write.

    line 101
  16. Distinctive:

    Never claim that hosted Notion MCP can upload files.

    line 103
  17. Distinctive:

    If access is wrong, disconnect or revoke it rather than continuing with a nearby workspace.

    line 104

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Setup Notion

Purpose

Configure Notion's official hosted MCP for this project, help the user complete browser OAuth, and verify the intended workspace before any content is created.

Current supported path

  • Official endpoint: https://mcp.notion.com/mcp
  • Transport: remote HTTP
  • Authentication: OAuth in the browser
  • Project configuration: .mcp.json

Notion's hosted MCP does not currently support file uploads. Do not promise that a local chart or other file can be uploaded through this server. Create the text page first. If the user needs an attachment, they can add it manually or use a separately approved API workflow.

Instructions

1. Inspect before changing configuration

  1. Read .mcp.json if it exists.
  2. Preserve every existing MCP server.
  3. Check whether a Notion server already points to the official endpoint.
  4. If Notion tools are already available, skip configuration and verify the connection.
  5. Before editing anything, show the user the exact non-secret change and ask for approval.

Never replace the entire MCP configuration merely to add Notion.

2. Add the official server

After approval, add this project-local server entry while preserving the rest of .mcp.json:

{
  "notion": {
    "type": "http",
    "url": "https://mcp.notion.com/mcp"
  }
}

An equivalent supported Claude Code command is:

claude mcp add --transport http --scope project notion https://mcp.notion.com/mcp

Do not put tokens or credentials in the configuration.

3. Authenticate

If this session did not load the new server, tell the user to restart Claude Code. Then have the user run /mcp, select Notion, and complete OAuth in the browser.

Before the user authorizes access, remind them to confirm:

  • the Notion account;
  • the workspace;
  • whether that workspace is approved for the intended work; and
  • that the connected client can act with the access granted to that user.

Do not claim that OAuth proves the destination or makes every future action safe.

4. Verify with a read

Ask the user for the title of a page they expect in the approved workspace. Use the available Notion search tool to find it without changing anything.

Show the workspace and matching page titles. If the expected page is missing, the workspace is wrong, or the tool call fails, stop and report the exact blocked step. Do not create a page.

5. Report the result

Report only what was verified:

Notion connection
Server: official hosted MCP
Endpoint: https://mcp.notion.com/mcp
Workspace: [verified workspace, if exposed]
Read test: [page title found, or exact blocked step]
Ready for an approved write: [yes or no]

Rules

  1. Use only Notion's official hosted endpoint unless the user explicitly requests another server.
  2. Preserve existing MCP servers.
  3. Stop for approval before editing MCP configuration.
  4. Never request or store a Notion API key for this OAuth path.
  5. Verify the workspace with a read before any write.
  6. Preview the destination and content before any later write.
  7. Never claim that hosted Notion MCP can upload files.
  8. If access is wrong, disconnect or revoke it rather than continuing with a nearby workspace.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.