Notion Agent Labbook

agent-labbook is a local MCP server that lets Codex, Claude Code, OpenCode, and other MCP clients use a Notion Internal Integration directly.

No OAuth, no hosted broker, no cloud worker. You connect Notion once, store the Internal Integration secret locally, bind the pages or data sources you want, and then call the official Notion API.

What It Does

Stores your Notion Internal Integration secret in the local system keychain
Lets an MCP client search, discover, and bind specific Notion pages or data sources
Returns API headers and bound resource IDs for direct Notion API calls
Provides a browser-based resource chooser for desktop environments

1. Create A Notion Internal Integration

Create a Notion Internal Integration here:

Notion integrations dashboard: notion.so/my-integrations
Notion guide: Create a Notion integration

After creating it:

Copy the Internal Integration Secret from the Configuration tab.
Share the target Notion pages or data sources with the integration.

2. Set The Token

Recommended on a workstation:

uvx agent-labbook configure-secret --storage keychain

CI or temporary override:

export NOTION_AGENT_LABBOOK_TOKEN=secret_xxx

Default policy:

keychain is the default local backend
NOTION_AGENT_LABBOOK_TOKEN is for CI or temporary overrides

3. Install The MCP Server

Codex:

codex mcp add labbook -- uvx agent-labbook mcp

Or add it directly to your ~/.codex/config.toml:

[mcp_servers.labbook]
command = "uvx"
args = ["agent-labbook", "mcp"]

Claude Code (project scope, writes to .mcp.json):

claude mcp add --scope local labbook -- uvx agent-labbook mcp

Claude Code (user scope, writes to ~/.claude.json):

claude mcp add --scope user labbook -- uvx agent-labbook mcp

OpenCode or other MCP clients:

{
  "mcpServers": {
    "labbook": {
      "command": "uvx",
      "args": ["agent-labbook", "mcp"]
    }
  }
}

You can also generate the config with:

uvx agent-labbook print-mcp-config

4. Use It

Typical flow:

Call notion_status to check the current project state.
Bind resources with notion_bind_resource_urls for exact links, notion_start_binding_server to hand the user a chooser URL, or notion_search_resources plus notion_discover_children in headless environments.
Call notion_get_api_context only when you are ready to use the official Notion API.

MCP Surface Reference

Tools (12)

Tool	Description	Read-only	Destructive
`notion_status`	Read the current Internal Integration auth, storage backend, and bindings status for this project.	Yes	No
`notion_setup_guide`	Return the setup guide for the Internal Integration workflow.	Yes	No
`notion_prepare_internal_integration`	Open the Notion integrations dashboard and detect available local storage backends before collecting the Internal Integration Secret.	No	No
`notion_configure_internal_integration`	Validate and store a Notion Internal Integration secret for this project.	No	No
`notion_search_resources`	Search the pages and data sources that the Internal Integration bot can access.	Yes	No
`notion_discover_children`	Inspect the immediate child pages or entries beneath a specific page or data source.	Yes	No
`notion_bind_resource_urls`	Bind one or more Notion page or data source URLs directly.	No	No
`notion_bind_resources`	Bind one or more Notion pages or data sources by reference.	No	No
`notion_start_binding_server`	Start a local binding chooser HTTP server (agent shares the URL; never launches a browser).	No	No
`notion_list_bindings`	List the Notion resources currently bound to this project.	Yes	No
`notion_get_api_context`	Return the Internal Integration secret, official Notion API headers, and bound resource IDs for direct API calls.	Yes	No
`notion_clear_project_auth`	Remove the saved project-local session and delete the stored keychain secret.	No	Yes

Resources (3)

Resource	URI	MIME Type	Description
Notion Setup Guide	`labbook://setup-guide`	`text/markdown`	Static setup guidance for using a Notion Internal Integration secret.
Notion Project Status	`labbook://project/status`	`application/json`	Read-only JSON snapshot of the current project's auth, storage backend, and bindings state.
Notion Project Bindings	`labbook://project/bindings`	`application/json`	Read-only JSON snapshot of the current project's bound Notion resources.

Resource Templates (2)

Template	URI Pattern	MIME Type	Description
Project Status By Root	`labbook://project/status?project_root={project_root}`	`application/json`	Read-only JSON project status for an explicit project root.
Project Bindings By Root	`labbook://project/bindings?project_root={project_root}`	`application/json`	Read-only JSON bindings for an explicit project root.

Prompts (2)

Prompt	Description
`notion_connect_project`	Recommended workflow for connecting the current project to Notion with an Internal Integration secret.
`notion_use_bound_resources`	Recommended workflow for checking bindings and calling the official Notion API with the project's configured secret.

CLI Commands

Command	Description
`agent-labbook mcp`	Run the MCP stdio server.
`agent-labbook configure-secret`	Prompt for the Notion Internal Integration secret and store it locally. Supports `--storage`.
`agent-labbook doctor`	Inspect local Notion Agent Labbook state and print diagnostics as JSON.
`agent-labbook print-mcp-config`	Print a reusable `uvx`-based MCP server config snippet.

Notes

.labbook/ stores project-local metadata and bindings, not the secret itself.
notion_get_api_context returns the secret. Use it only for real API calls.
NOTION_AGENT_LABBOOK_TOKEN overrides stored local credentials for the current process.
The MCP server runs over stdio transport only. No HTTP/SSE transport is exposed.

License

MIT

Release files for agent-labbook 0.19.13

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for agent-labbook 0.19.13
File	Size	Uploaded
agent_labbook-0.19.13.tar.gz	63.8 kB	Apr 16, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for agent-labbook 0.19.13
File	Interpreter	ABI	Platform	Reset
agent_labbook-0.19.13-py3-none-any.whl 48.8 kB Apr 16, 2026	Python 3	none	any	Details

Total release size: 112.7 kB

Release files / agent_labbook-0.19.13.tar.gz

Download URL	agent_labbook-0.19.13.tar.gz
Size	63.8 kB
Tags	Source
SHA-256 checksum How to use checksums	`f405de52cc299a215a61bfa5dfb6669c20887cb5d2eb32b1c3126e23f801d4b3`
BLAKE2b-256 checksum How to use checksums	`bb51d7b0671248de1afba5ca803281fff815f66915db2298f29cb9ebbfa40c41`
Upload date	Apr 16, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.13.12`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/binbinsh/agent-labbook
Publishing commit: github.com/binbinsh/agent-labbook/tree/a679ae69b2ac56a39d11bd4e634384e069879bbd

Workflow

Publishing configuration: github.com/binbinsh/agent-labbook/blob/a679ae69b2ac56a39d11bd4e634384e069879bbd/.github/workflows/publish-pypi.yml
Publishing logs: github.com/binbinsh/agent-labbook/actions/runs/24529893610/attempts/1

Artifact

Subject: agent_labbook-0.19.13.tar.gz
SHA-256 checksum: f405de52cc299a215a61bfa5dfb6669c20887cb5d2eb32b1c3126e23f801d4b3 Verifying attestations

Release files / agent_labbook-0.19.13-py3-none-any.whl

Download URL	agent_labbook-0.19.13-py3-none-any.whl
Size	48.8 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`a888330dabb5ad82e6c1f2f90e9ab748d3acf3da7d1188e0e3c72b70c17aa0b2`
BLAKE2b-256 checksum How to use checksums	`b7c4b7c7b91cf849bbe829ef070c4925cc10a1f1aeb360998854eb91a7f30e57`
Upload date	Apr 16, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.13.12`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/binbinsh/agent-labbook
Publishing commit: github.com/binbinsh/agent-labbook/tree/a679ae69b2ac56a39d11bd4e634384e069879bbd

Workflow

Publishing configuration: github.com/binbinsh/agent-labbook/blob/a679ae69b2ac56a39d11bd4e634384e069879bbd/.github/workflows/publish-pypi.yml
Publishing logs: github.com/binbinsh/agent-labbook/actions/runs/24529893610/attempts/1

Artifact

Subject: agent_labbook-0.19.13-py3-none-any.whl
SHA-256 checksum: a888330dabb5ad82e6c1f2f90e9ab748d3acf3da7d1188e0e3c72b70c17aa0b2 Verifying attestations