@agentx-ai/notion-mcp-server
Version:
AgentX MCP server for Notion API with user-friendly environment variables
1,225 lines • 95.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 by their ID. This tool requires Notion Enterprise plan and Organization API key with correct permissions.",
"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 in Notion workspace. This tool requires Notion Enterprise plan and Organization API key with correct permissions.",
"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. Must be a valid UUID. If not know, skip and DO NOT include it.",
"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 yourself as a user with the current setup token in Notion",
"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. Must be a valid UUID. If not know, skip and DO NOT include it."
},
"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`. Must be a valid UUID. If not know, skip and DO NOT include it."
},
"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. Must be a valid UUID. If not know, skip and DO NOT include it.",
"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 new children blocks to a specified parent block in Notion. For insert or write content to a block or a page. You can optionally specify the 'after' parameter to append after a certain block.",
"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": {
"heading_1": {
"type": "object",
"description": "A heading block. Can replace with heading_2, heading_3 (e.g. {\"type\": \"heading_1\", \"heading_1\": {\"rich_text\": [{\"type\": \"text\", \"text\": {\"content\": \"Hello, world!\"}}]}})",
"properties": {
"rich_text": {
"type": "array",
"items": {
"type": "object",
"description": "A text object. e.g. {\"type\": \"text\", \"text\": {\"content\": \"Hello, world!\"}}"
}
}
}
},
"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 in Notion based on its type. The update replaces the entire value for a given field.",
"description": "",
"operationId": "update-a-block",
"parameters": [
{
"name": "block_id",
"in": "path",
"description": "Identifier for a Notion block, must be a valid UUID",
"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. page_id is required. If you do not have the page_id, you can either run post-search to get it, or ask the user which page to create under.",
"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 for a Notion page. page_id is required. If you do not have the page_id, you can either run post-search to get it, or ask the user which page to create under.",
"description": "",
"operationId": "patch-page",
"parameters": [
{
"name": "page_id",
"in": "path",
"description": "The identifier for the Notion page to be updated. Must be a valid UUID",
"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": {
"tex