Otto Notion MCP Server

A lightweight Notion integration MCP server for Otto. Provides basic read/write capabilities to Notion pages, treating Notion as a scratchpad or output location.

Features

• 🔍 Read pages: Extract Notion page content as markdown
• ✍️ Write pages: Create new pages with markdown content
• ✏️ Edit pages: Replace existing page content
• 📝 Markdown support: Headings, lists, code blocks, bold, italic, links
• 🎯 Minimal: Only 3 tools - no workspace management overhead
• 🔒 Constrained: All pages created under a single configured parent

Installation

For Use with Otto

1. Install via NPX (recommended):

   npx -y otto-notion

2. Get Notion API Key:

   • Go to https://www.notion.so/my-integrations
   • Create a new integration
   • Copy the API key (starts with secret_)

3. Get Parent Page ID:

   • Open the parent page in Notion where Otto should create pages
   • Share the page with your integration
   • Copy the page ID from the URL: https://notion.so/workspace/PAGE_ID_HERE

4. Configure in Otto's mcp-config.json:

   {
     "mcpServers": {
       "otto-notion": {
         "command": "npx",
         "args": ["-y", "otto-notion"],
         "env": {
           "NOTION_API_KEY": "secret_your_api_key_here",
           "NOTION_PARENT_PAGE_ID": "your_parent_page_id_here"
         },
         "transport": "stdio"
       }
     }
   }

For Development

1. Clone the repository:

   git clone <repository-url>
   cd otto-notion

2. Install dependencies:

   npm install

3. Create .env file:

   cp .env.example .env
   # Edit .env and add your credentials

4. Build:

   npm run build

5. Run in development:

   npm run dev

MCP Tools

notion_read_page

Read a Notion page and return its content as markdown.

Parameters:

• id (optional): Notion page ID
• link (optional): Notion page URL

Example:

{
  "name": "notion_read_page",
  "arguments": {
    "link": "https://notion.so/workspace/My-Page-abc123..."
  }
}

Returns:

# Page Title

Page content in markdown format...

notion_write_page

Create a new page under the configured parent page.

Parameters:

• title (required): Page title
• content (required): Page content as markdown

Example:

{
  "name": "notion_write_page",
  "arguments": {
    "title": "Meeting Notes",
    "content": "# Agenda\n\n- Topic 1\n- Topic 2\n\n## Action Items\n\n1. Review code\n2. Update docs"
  }
}

Returns:

Successfully created page: "Meeting Notes"
URL: https://notion.so/abc123...
ID: abc123...

notion_edit_page

Replace the entire content of an existing page. Optionally update the title.

Parameters:

• id (optional): Notion page ID
• link (optional): Notion page URL
• content (required): New content as markdown
• title (optional): New title

Example:

{
  "name": "notion_edit_page",
  "arguments": {
    "id": "abc123...",
    "content": "# Updated Content\n\nThis replaces all existing content.",
    "title": "New Title"
  }
}

Returns:

Successfully updated page with new title: "New Title"
URL: https://notion.so/abc123...
ID: abc123...

Supported Markdown

✅ Supported in MVP

• Headings: # H1, ## H2, ### H3
• Paragraphs: Regular text
• Lists:
  • Bullet: - item
  • Numbered: 1. item
• Code blocks: ```language\ncode\n```
• Inline formatting:
  • Bold: **text**
  • Italic: *text*
  • Strikethrough: ~~text~~
  • Code: `code`
  • Links: [text](url)

❌ Not Yet Supported

• Tables
• Images/embeds
• Callouts
• Toggle lists
• Databases

Architecture

otto-notion/
├── src/
│   ├── index.ts           # Entry point
│   ├── server.ts          # MCP server implementation
│   ├── notion-client.ts   # Notion API wrapper
│   ├── converters.ts      # Markdown ↔ Notion blocks
│   └── types.ts           # TypeScript definitions
├── package.json
├── tsconfig.json
└── README.md

Development

Running Tests

npm test

Type Checking

npm run typecheck

Building

npm run build

Testing with MCP Inspector

npm install -g @modelcontextprotocol/inspector
mcp-inspector npx otto-notion

Integration with Otto

Otto's MCP manager will:

1. Load this server from mcp-config.json
2. Execute npx -y otto-notion
3. Initialize connection via stdio transport
4. Discover the 3 tools via MCP protocol
5. Make tools available to the agent

No changes needed to Otto's core code - this is purely additive via MCP.

Troubleshooting

"NOTION_API_KEY environment variable is required"

Make sure you've set the API key in your mcp-config.json env section:

{
  "env": {
    "NOTION_API_KEY": "secret_your_key_here"
  }
}

"Page not found" or "Permission denied"

The Notion integration must be shared with the pages you want to access:

1. Open the page in Notion
2. Click "Share" in the top right
3. Invite your integration

"Invalid page ID or URL"

Supported formats:

• UUID: abc12345-1234-1234-1234-123456789abc
• 32-char hex: abc123... (will be auto-converted to UUID)
• URL: https://notion.so/workspace/Page-Title-abc123...

License

MIT

Contributing

Contributions welcome! Please open an issue or PR.

Links

• Notion API Documentation
• Model Context Protocol
• Otto Agent