agent-labbook

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:

1. Copy the Internal Integration Secret from the Configuration tab.
2. 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:

1. Call notion_status to check the current project state.
2. 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.
3. Call notion_get_api_context only when you are ready to use the official Notion API.

MCP Surface Reference

Tools (12)

Resources (3)

Resource Templates (2)

Prompts (2)

CLI Commands

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