@notionhq/notion-mcp-server
Version:
Official MCP server for Notion API
1,260 lines • 96.1 kB
JSON
{
"openapi": "3.1.0",
"info": {
"title": "Notion API",
"version": "1"
},
"servers": [
{
"url": "https://api.notion.com"
}
],
"components": {
"securitySchemes": {
"bearerAuth": {
"type": "http",
"scheme": "bearer"
},
"basicAuth": {
"type": "http",
"scheme": "basic"
}
},
"parameters": {},
"schemas": {}
},
"security": [
{
"bearerAuth": []
}
],
"paths": {
"/v1/users/{user_id}": {
"get": {
"summary": "Retrieve a user",
"description": "",
"operationId": "get-user",
"parameters": [
{
"name": "user_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "200",
"content": {
"application/json": {
"examples": {
"Result": {
"value": "{\n \"object\": \"user\",\n \"id\": \"d40e767c-d7af-4b18-a86d-55c61f1e39a4\",\n \"type\": \"person\",\n\t\"person\": {\n\t\t\"email\": \"avo@example.org\",\n\t},\n \"name\": \"Avocado Lovelace\",\n \"avatar_url\": \"https://secure.notion-static.com/e6a352a8-8381-44d0-a1dc-9ed80e62b53d.jpg\",\n}"
}
}
}
}
},
"400": {
"description": "400",
"content": {
"application/json": {
"examples": {
"Result": {
"value": "{}"
}
},
"schema": {
"type": "object",
"properties": {}
}
}
}
}
},
"deprecated": false,
"security": []
}
},
"/v1/users": {
"get": {
"summary": "List all users",
"operationId": "get-users",
"parameters": [
{
"name": "start_cursor",
"in": "query",
"description": "If supplied, this endpoint will return a page of results starting after the cursor provided. If not supplied, this endpoint will return the first page of results.",
"schema": {
"type": "string"
}
},
{
"name": "page_size",
"in": "query",
"description": "The number of items from the full list desired in the response. Maximum: 100",
"schema": {
"type": "integer",
"default": 100
}
}
],
"responses": {
"400": {
"description": "400",
"content": {
"application/json": {
"examples": {
"Result": {
"value": "{}"
}
},
"schema": {
"type": "object",
"properties": {}
}
}
}
}
},
"deprecated": false
}
},
"/v1/users/me": {
"get": {
"summary": "Retrieve your token's bot user",
"description": "",
"operationId": "get-self",
"parameters": [],
"responses": {
"200": {
"description": "200",
"content": {
"application/json": {
"examples": {
"Result": {
"value": "{\n \"object\": \"user\",\n \"id\": \"16d84278-ab0e-484c-9bdd-b35da3bd8905\",\n \"name\": \"pied piper\",\n \"avatar_url\": null,\n \"type\": \"bot\",\n \"bot\": {\n \"owner\": {\n \"type\": \"user\",\n \"user\": {\n \"object\": \"user\",\n \"id\": \"5389a034-eb5c-47b5-8a9e-f79c99ef166c\",\n \"name\": \"christine makenotion\",\n \"avatar_url\": null,\n \"type\": \"person\",\n \"person\": {\n \"email\": \"christine@makenotion.com\"\n }\n }\n }\n }\n}"
}
},
"schema": {
"type": "object",
"properties": {
"object": {
"type": "string",
"example": "user"
},
"id": {
"type": "string",
"example": "16d84278-ab0e-484c-9bdd-b35da3bd8905"
},
"name": {
"type": "string",
"example": "pied piper"
},
"avatar_url": {},
"type": {
"type": "string",
"example": "bot"
},
"bot": {
"type": "object",
"properties": {
"owner": {
"type": "object",
"properties": {
"type": {
"type": "string",
"example": "user"
},
"user": {
"type": "object",
"properties": {
"object": {
"type": "string",
"example": "user"
},
"id": {
"type": "string",
"example": "5389a034-eb5c-47b5-8a9e-f79c99ef166c"
},
"name": {
"type": "string",
"example": "christine makenotion"
},
"avatar_url": {},
"type": {
"type": "string",
"example": "person"
},
"person": {
"type": "object",
"properties": {
"email": {
"type": "string",
"example": "christine@makenotion.com"
}
}
}
}
}
}
}
}
}
}
}
}
}
}
},
"deprecated": false,
"security": []
}
},
"/v1/databases/{database_id}/query": {
"post": {
"summary": "Query a database",
"description": "",
"operationId": "post-database-query",
"parameters": [
{
"name": "database_id",
"in": "path",
"description": "Identifier for a Notion database.",
"schema": {
"type": "string"
},
"required": true
},
{
"name": "filter_properties",
"in": "query",
"description": "A list of page property value IDs associated with the database. Use this param to limit the response to a specific page property value or values for pages that meet the `filter` criteria.",
"schema": {
"type": "array",
"items": {
"type": "string"
}
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"filter": {
"type": "object",
"description": "When supplied, limits which pages are returned based on the [filter conditions](ref:post-database-query-filter).",
"or": {
"type": "array",
"items": {
"type": "object",
"properties": {
"type": "object",
"properties": {
"property": {
"type": "string"
},
"title": {
"type": "object",
"properties": {
"equals": {
"type": "string"
},
"does_not_equal": {
"type": "string"
},
"contains": {
"type": "string"
},
"does_not_contain": {
"type": "string"
},
"starts_with": {
"type": "string"
},
"ends_with": {
"type": "string"
}
}
},
"rich_text": {
"type": "object",
"properties": {
"equals": {
"type": "string"
},
"does_not_equal": {
"type": "string"
},
"contains": {
"type": "string"
},
"does_not_contain": {
"type": "string"
},
"starts_with": {
"type": "string"
},
"ends_with": {
"type": "string"
}
}
},
"url": {
"type": "object",
"properties": {
"equals": {
"type": "string"
},
"does_not_equal": {
"type": "string"
},
"contains": {
"type": "string"
},
"does_not_contain": {
"type": "string"
},
"starts_with": {
"type": "string"
},
"ends_with": {
"type": "string"
}
}
},
"email": {
"type": "object",
"properties": {
"equals": {
"type": "string"
},
"does_not_equal": {
"type": "string"
},
"contains": {
"type": "string"
},
"does_not_contain": {
"type": "string"
},
"starts_with": {
"type": "string"
},
"ends_with": {
"type": "string"
}
}
},
"phone_number": {
"type": "object",
"properties": {
"equals": {
"type": "string"
},
"does_not_equal": {
"type": "string"
},
"contains": {
"type": "string"
},
"does_not_contain": {
"type": "string"
},
"starts_with": {
"type": "string"
},
"ends_with": {
"type": "string"
}
}
},
"number": {
"type": "object",
"properties": {
"equals": {
"type": "number"
},
"does_not_equal": {
"type": "number"
},
"contains": {
"type": "number"
},
"does_not_contain": {
"type": "number"
},
"starts_with": {
"type": "number"
},
"ends_with": {
"type": "number"
}
}
},
"checkbox": {
"type": "object",
"properties": {
"equals": {
"type": "boolean"
},
"does_not_equal": {
"type": "boolean"
}
}
},
"select": {
"type": "object",
"properties": {
"equals": {
"type": "string"
},
"does_not_equal": {
"type": "string"
}
}
},
"multi_select": {
"type": "object",
"properties": {
"contains": {
"type": "string"
},
"does_not_contain": {
"type": "string"
}
}
},
"status": {
"type": "object",
"properties": {
"equals": {
"type": "string"
},
"does_not_equal": {
"type": "string"
}
}
},
"date": {
"type": "object",
"properties": {
"equals": {
"type": "string",
"format": "date"
},
"before": {
"type": "string",
"format": "date"
},
"after": {
"type": "string",
"format": "date"
},
"on_or_before": {
"type": "string",
"format": "date"
},
"on_or_after": {
"type": "string",
"format": "date"
}
}
},
"created_time": {
"type": "object",
"properties": {
"equals": {
"type": "string",
"format": "date"
},
"before": {
"type": "string",
"format": "date"
},
"after": {
"type": "string",
"format": "date"
},
"on_or_before": {
"type": "string",
"format": "date"
},
"on_or_after": {
"type": "string",
"format": "date"
}
}
},
"last_edited_time": {
"type": "object",
"properties": {
"equals": {
"type": "string",
"format": "date"
},
"before": {
"type": "string",
"format": "date"
},
"after": {
"type": "string",
"format": "date"
},
"on_or_before": {
"type": "string",
"format": "date"
},
"on_or_after": {
"type": "string",
"format": "date"
}
}
}
}
}
},
"maxItems": 100
},
"and": {
"type": "array",
"items": {
"type": "object",
"properties": {
"type": "object",
"properties": {
"property": {
"type": "string"
},
"title": {
"type": "object",
"properties": {
"equals": {
"type": "string"
},
"does_not_equal": {
"type": "string"
},
"contains": {
"type": "string"
},
"does_not_contain": {
"type": "string"
},
"starts_with": {
"type": "string"
},
"ends_with": {
"type": "string"
}
}
},
"rich_text": {
"type": "object",
"properties": {
"equals": {
"type": "string"
},
"does_not_equal": {
"type": "string"
},
"contains": {
"type": "string"
},
"does_not_contain": {
"type": "string"
},
"starts_with": {
"type": "string"
},
"ends_with": {
"type": "string"
}
}
},
"url": {
"type": "object",
"properties": {
"equals": {
"type": "string"
},
"does_not_equal": {
"type": "string"
},
"contains": {
"type": "string"
},
"does_not_contain": {
"type": "string"
},
"starts_with": {
"type": "string"
},
"ends_with": {
"type": "string"
}
}
},
"email": {
"type": "object",
"properties": {
"equals": {
"type": "string"
},
"does_not_equal": {
"type": "string"
},
"contains": {
"type": "string"
},
"does_not_contain": {
"type": "string"
},
"starts_with": {
"type": "string"
},
"ends_with": {
"type": "string"
}
}
},
"phone_number": {
"type": "object",
"properties": {
"equals": {
"type": "string"
},
"does_not_equal": {
"type": "string"
},
"contains": {
"type": "string"
},
"does_not_contain": {
"type": "string"
},
"starts_with": {
"type": "string"
},
"ends_with": {
"type": "string"
}
}
},
"number": {
"type": "object",
"properties": {
"equals": {
"type": "number"
},
"does_not_equal": {
"type": "number"
},
"contains": {
"type": "number"
},
"does_not_contain": {
"type": "number"
},
"starts_with": {
"type": "number"
},
"ends_with": {
"type": "number"
}
}
},
"checkbox": {
"type": "object",
"properties": {
"equals": {
"type": "boolean"
},
"does_not_equal": {
"type": "boolean"
}
}
},
"select": {
"type": "object",
"properties": {
"equals": {
"type": "string"
},
"does_not_equal": {
"type": "string"
}
}
},
"multi_select": {
"type": "object",
"properties": {
"contains": {
"type": "string"
},
"does_not_contain": {
"type": "string"
}
}
},
"status": {
"type": "object",
"properties": {
"equals": {
"type": "string"
},
"does_not_equal": {
"type": "string"
}
}
},
"date": {
"type": "object",
"properties": {
"equals": {
"type": "string",
"format": "date"
},
"before": {
"type": "string",
"format": "date"
},
"after": {
"type": "string",
"format": "date"
},
"on_or_before": {
"type": "string",
"format": "date"
},
"on_or_after": {
"type": "string",
"format": "date"
}
}
},
"created_time": {
"type": "object",
"properties": {
"equals": {
"type": "string",
"format": "date"
},
"before": {
"type": "string",
"format": "date"
},
"after": {
"type": "string",
"format": "date"
},
"on_or_before": {
"type": "string",
"format": "date"
},
"on_or_after": {
"type": "string",
"format": "date"
}
}
},
"last_edited_time": {
"type": "object",
"properties": {
"equals": {
"type": "string",
"format": "date"
},
"before": {
"type": "string",
"format": "date"
},
"after": {
"type": "string",
"format": "date"
},
"on_or_before": {
"type": "string",
"format": "date"
},
"on_or_after": {
"type": "string",
"format": "date"
}
}
}
}
}
},
"maxItems": 100
}
},
"sorts": {
"type": "array",
"description": "When supplied, orders the results based on the provided [sort criteria](ref:post-database-query-sort).",
"items": {
"type": "object",
"required": [
"property",
"direction"
],
"properties": {
"property": {
"type": "string"
},
"direction": {
"enum": [
"ascending",
"descending"
],
"type": "string"
}
}
}
},
"start_cursor": {
"type": "string",
"description": "When supplied, returns a page of results starting after the cursor provided. If not supplied, this endpoint will return the first page of results."
},
"page_size": {
"type": "integer",
"description": "The number of items from the full list desired in the response. Maximum: 100",
"default": 100
},
"archived": {
"type": "boolean"
},
"in_trash": {
"type": "boolean"
}
}
}
}
}
},
"responses": {},
"deprecated": false,
"security": []
}
},
"/v1/search": {
"post": {
"summary": "Search by title",
"description": "",
"operationId": "post-search",
"parameters": [],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "The text that the API compares page and database titles against."
},
"sort": {
"type": "object",
"description": "A set of criteria, `direction` and `timestamp` keys, that orders the results. The **only** supported timestamp value is `\"last_edited_time\"`. Supported `direction` values are `\"ascending\"` and `\"descending\"`. If `sort` is not provided, then the most recently edited results are returned first.",
"properties": {
"direction": {
"type": "string",
"description": "The direction to sort. Possible values include `ascending` and `descending`."
},
"timestamp": {
"type": "string",
"description": "The name of the timestamp to sort against. Possible values include `last_edited_time`."
}
}
},
"filter": {
"type": "object",
"description": "A set of criteria, `value` and `property` keys, that limits the results to either only pages or only databases. Possible `value` values are `\"page\"` or `\"database\"`. The only supported `property` value is `\"object\"`.",
"properties": {
"value": {
"type": "string",
"description": "The value of the property to filter the results by. Possible values for object type include `page` or `database`. **Limitation**: Currently the only filter allowed is `object` which will filter by type of object (either `page` or `database`)"
},
"property": {
"type": "string",
"description": "The name of the property to filter by. Currently the only property you can filter by is the object type. Possible values include `object`. Limitation: Currently the only filter allowed is `object` which will filter by type of object (either `page` or `database`)"
}
}
},
"start_cursor": {
"type": "string",
"description": "A `cursor` value returned in a previous response that If supplied, limits the response to results starting after the `cursor`. If not supplied, then the first page of results is returned. Refer to [pagination](https://developers.notion.com/reference/intro#pagination) for more details."
},
"page_size": {
"type": "integer",
"description": "The number of items from the full list to include in the response. Maximum: `100`.",
"default": 100,
"format": "int32"
}
}
}
}
}
},
"responses": {},
"deprecated": false,
"security": []
}
},
"/v1/blocks/{block_id}/children": {
"get": {
"summary": "Retrieve block children",
"description": "",
"operationId": "get-block-children",
"parameters": [
{
"name": "block_id",
"in": "path",
"description": "Identifier for a [block](ref:block)",
"schema": {
"type": "string"
},
"required": true
},
{
"name": "start_cursor",
"in": "query",
"description": "If supplied, this endpoint will return a page of results starting after the cursor provided. If not supplied, this endpoint will return the first page of results.",
"schema": {
"type": "string"
}
},
{
"name": "page_size",
"in": "query",
"description": "The number of items from the full list desired in the response. Maximum: 100",
"schema": {
"type": "integer",
"format": "int32",
"default": 100
}
}
],
"responses": {},
"deprecated": false,
"security": []
},
"patch": {
"summary": "Append block children",
"description": "",
"operationId": "patch-block-children",
"parameters": [
{
"name": "block_id",
"in": "path",
"description": "Identifier for a [block](ref:block). Also accepts a [page](ref:page) ID.",
"schema": {
"type": "string"
},
"required": true
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"children"
],
"properties": {
"children": {
"type": "array",
"items": {
"type": "object",
"properties": {
"paragraph": {
"type": "object",
"properties": {
"rich_text": {
"type": "array",
"items": {
"type": "object",
"properties": {
"text": {
"type": "object",
"properties": {
"content": {
"type": "string"
},
"link": {
"type": [
"object",
"null"
],
"properties": {
"url": {
"type": "string"
}
},
"required": [
"url"
]
}
},
"additionalProperties": false,
"required": [
"content"
]
},
"type": {
"enum": [
"text"
],
"type": "string"
}
},
"additionalProperties": false,
"required": [
"text"
]
},
"maxItems": 100
}
},
"additionalProperties": false,
"required": [
"rich_text"
]
},
"bulleted_list_item": {
"type": "object",
"properties": {
"rich_text": {
"type": "array",
"items": {
"type": "object",
"properties": {
"text": {
"type": "object",
"properties": {
"content": {
"type": "string"
},
"link": {
"type": [
"object",
"null"
],
"properties": {
"url": {
"type": "string"
}
},
"required": [
"url"
]
}
},
"additionalProperties": false,
"required": [
"content"
]
},
"type": {
"enum": [
"text"
],
"type": "string"
}
},
"additionalProperties": false,
"required": [
"text"
]
},
"maxItems": 100
}
},
"additionalProperties": false,
"required": [
"rich_text"
]
},
"type": {
"enum": [
"paragraph",
"bulleted_list_item"
],
"type": "string"
}
},
"additionalProperties": false
},
"description": "Child content to append to a container block as an array of [block objects](ref:block)"
},
"after": {
"type": "string",
"description": "The ID of the existing block that the new block should be appended after."
}
}
}
}
}
},
"responses": {},
"deprecated": false,
"security": []
}
},
"/v1/blocks/{block_id}": {
"get": {
"summary": "Retrieve a block",
"description": "",
"operationId": "retrieve-a-block",
"parameters": [
{
"name": "block_id",
"in": "path",
"description": "Identifier for a Notion block",
"schema": {
"type": "string"
},
"required": true
}
],
"responses": {},
"deprecated": false,
"security": []
},
"patch": {
"summary": "Update a block",
"description": "",
"operationId": "update-a-block",
"parameters": [
{
"name": "block_id",
"in": "path",
"description": "Identifier for a Notion block",
"schema": {
"type": "string"
},
"required": true
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"type": {
"type": "object",
"description": "The [block object `type`](ref:block#block-object-keys) value with the properties to be updated. Currently only `text` (for supported block types) and `checked` (for `to_do` blocks) fields can be updated.",
"properties": {}
},
"archived": {
"type": "boolean",
"description": "Set to true to archive (delete) a block. Set to false to un-archive (restore) a block.",
"default": true
}
}
}
}
}
},
"responses": {},
"deprecated": false,
"security": []
},
"delete": {
"summary": "Delete a block",
"description": "",
"operationId": "delete-a-block",
"parameters": [
{
"name": "block_id",
"in": "path",
"description": "Identifier for a Notion block",
"schema": {
"type": "string"
},
"required": true
}
],
"responses": {},
"deprecated": false,
"security": []
}
},
"/v1/pages/{page_id}": {
"get": {
"summary": "Retrieve a page",
"description": "",
"operationId": "retrieve-a-page",
"parameters": [
{
"name": "page_id",
"in": "path",
"description": "Identifier for a Notion page",
"schema": {
"type": "string"
},
"required": true
},
{
"name": "filter_properties",
"in": "query",
"description": "A list of page property value IDs associated with the page. Use this param to limit the response to a specific page property value or values. To retrieve multiple properties, specify each page property ID. For example: `?filter_properties=iAk8&filter_properties=b7dh`.",
"schema": {
"type": "string"
}
}
],
"responses": {},
"deprecated": false,
"security": []
},
"patch": {
"summary": "Update page properties",
"description": "",
"operationId": "patch-page",
"parameters": [
{
"name": "page_id",
"in": "path",
"description": "The identifier for the Notion page to be updated.",
"schema": {
"type": "string"
},
"required": true
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"properties": {
"description": "The property values to update for the page. The keys are the names or IDs of the property and the values are property values. If a page property ID is not included, then it is not changed.",
"type": "object",
"properties": {
"title": {
"type": "array",
"items": {
"type": "object",
"properties": {
"text": {
"type": "object",
"properties": {
"content": {
"type": "string"
},
"link": {
"type": [
"object",
"null"
],
"properties": {