notion-mcp

What this skill does

# Notion MCP

Access Notion via MCP (Model Context Protocol) with managed authentication.

## Quick Start

```bash
python <<'EOF'
import urllib.request, os, json
data = json.dumps({'query': 'meeting notes', 'query_type': 'internal'}).encode()
req = urllib.request.Request('https://gateway.maton.ai/notion/notion-search', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF
```

## Base URL

```
https://gateway.maton.ai/notion/{tool-name}
```

Replace `{tool-name}` with the MCP tool name (e.g., `notion-search`). The gateway proxies requests to `mcp.notion.com` and automatically injects your credentials.

## Request Headers

MCP requests use the `Mcp-Session-Id` header for session management. If not specified, the gateway initializes a new session and returns the session ID in the `Mcp-Session-Id` response header. You can include this session ID in subsequent requests to reuse the same session.

## Authentication

All requests require the Maton API key:

```
Authorization: Bearer $MATON_API_KEY
```

**Environment Variable:** Set your API key as `MATON_API_KEY`:

```bash
export MATON_API_KEY="YOUR_API_KEY"
```

### Getting Your API Key

1. Sign in or create an account at [maton.ai](https://maton.ai)
2. Go to [maton.ai/settings](https://maton.ai/settings)
3. Copy your API key

## Connection Management

Manage your Notion MCP connections at `https://ctrl.maton.ai`.

### List Connections

```bash
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections?app=notion&method=MCP&status=ACTIVE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF
```

### Create Connection

```bash
python <<'EOF'
import urllib.request, os, json
data = json.dumps({'app': 'notion', 'method': 'MCP'}).encode()
req = urllib.request.Request('https://ctrl.maton.ai/connections', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF
```

### Get Connection

```bash
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF
```

**Response:**
```json
{
  "connection": {
    "connection_id": "21fd90f9-5935-43cd-b6c8-bde9d915ca80",
    "status": "PENDING",
    "creation_time": "2025-12-08T07:20:53.488460Z",
    "url": "https://connect.maton.ai/?session_token=...",
    "app": "notion",
    "method": "MCP",
    "metadata": {}
  }
}
```

Open the returned `url` in a browser to complete OAuth authorization.

### Delete Connection

```bash
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}', method='DELETE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF
```

### Specifying Connection

If you have multiple Notion connections (eg. OAuth2, MCP), you must specify which MCP connection to use with the `Maton-Connection` header:

```bash
python <<'EOF'
import urllib.request, os, json
data = json.dumps({'query': 'meeting notes', 'query_type': 'internal'}).encode()
req = urllib.request.Request('https://gateway.maton.ai/notion/notion-search', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
req.add_header('Maton-Connection', '21fd90f9-5935-43cd-b6c8-bde9d915ca80')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF
```

IMPORTANT: If omitted, the gateway uses the default (oldest) active connection, which may fail if it's not an MCP connection.

## MCP Reference

All MCP tools use `POST` method:

| Tool | Description | Schema |
|------|-------------|--------|
| `notion-search` | Search workspace and connected services | [schema](schemas/notion-search.json) |
| `notion-fetch` | Retrieve content from pages/databases | [schema](schemas/notion-fetch.json) |
| `notion-create-pages` | Create pages with properties and content | [schema](schemas/notion-create-pages.json) |
| `notion-update-page` | Update page properties and content | [schema](schemas/notion-update-page.json) |
| `notion-move-pages` | Relocate pages to new parent | [schema](schemas/notion-move-pages.json) |
| `notion-duplicate-page` | Copy pages within workspace | [schema](schemas/notion-duplicate-page.json) |
| `notion-create-database` | Create databases with schema | [schema](schemas/notion-create-database.json) |
| `notion-update-data-source` | Modify data source attributes | [schema](schemas/notion-update-data-source.json) |
| `notion-create-comment` | Add comments to pages/blocks | [schema](schemas/notion-create-comment.json) |
| `notion-get-comments` | Retrieve page comments | [schema](schemas/notion-get-comments.json) |
| `notion-get-teams` | List workspace teams | [schema](schemas/notion-get-teams.json) |
| `notion-get-users` | List workspace users | [schema](schemas/notion-get-users.json) |

### Search

Search for pages and databases:
```bash
POST /notion/notion-search
Content-Type: application/json

{
  "query": "meeting notes",
  "query_type": "internal"
}
```

**Response:**
```json
{
  "content": [
    {
      "type": "text",
      "text": "{\"results\":[{\"id\":\"30702dc5-9a3b-8106-b51b-ed6d1bfeeed4\",\"title\":\"Meeting Summary Report\",\"url\":\"https://www.notion.so/30702dc59a3b8106b51bed6d1bfeeed4\",\"type\":\"page\",\"highlight\":\"Meeting materials\",\"timestamp\":\"2026-02-15T00:07:00.000Z\"}],\"type\":\"workspace_search\"}"
    }
  ],
  "isError": false
}
```

Search for users:
```bash
POST /notion/notion-search
Content-Type: application/json

{
  "query": "[email protected]",
  "query_type": "user"
}
```

With date filter:
```bash
POST /notion/notion-search
Content-Type: application/json

{
  "query": "quarterly report",
  "query_type": "internal",
  "filters": {
    "created_date_range": {
      "start_date": "2024-01-01",
      "end_date": "2025-01-01"
    }
  }
}
```

### Fetch Content

Fetch page by URL:
```bash
POST /notion/notion-fetch
Content-Type: application/json

{
  "id": "https://notion.so/workspace/Page-a1b2c3d4e5f67890"
}
```

**Response:**
```json
{
  "content": [
    {
      "type": "text",
      "text": "{\"metadata\":{\"type\":\"page\"},\"title\":\"Project Overview\",\"url\":\"https://www.notion.so/30702dc59a3b8106b51bed6d1bfeeed4\",\"text\":\"Here is the result of \\\"view\\\" for the Page with URL https://www.notion.so/30702dc59a3b8106b51bed6d1bfeeed4 as of 2026-02-14T22:56:21.276Z:\\n<page url=\\\"https://www.notion.so/30702dc59a3b8106b51bed6d1bfeeed4\\\">\\n<properties>\\n{\\\"title\\\":\\\"Project Overview\\\"}\\n</properties>\\n<content>\\n# Project Overview\\n\\nThis document outlines the project goals and milestones.\\n</content>\\n</page>\"}"
    }
  ],
  "isError": false
}
```

Fetch by UUID:
```bash
POST /notion/notion-fetch
Content-Type: application/json

{
  "id": "12345678-90ab-cdef-1234-567890abcdef"
}
```

Fetch data source (collection):
```bash
POST /notion/notion-fetch
Content-Type: application/json

{
  "id": "collection://12345678-90ab-cdef-1234-567890abcdef"
}
```

Include discussions:
```bash
POST /notion/notion-fetch
Content-Type: application/json

{
  "id": "page-uuid",
  "include_discussions": true
}
```

### Create Pages

Create a simple page:
```bash
POST /notion/notion-create-pages
Content-Type: application/json

{
  "pages": [
    {
      "properties": {"title": "My New Page"},
      "content": "# Introdu