# Notion MCP Server

A Model Context Protocol (MCP) server for interacting with Notion workspaces. Built with Python and FastMCP.

## Features

- **Search**: Global search across pages and databases
- **Databases**: Query, create entries, get schema
- **Pages**: Create, read, update, archive pages
- **Blocks**: Read and append content blocks
- **Users**: List workspace users

## Installation

```bash
pip install -r requirements.txt
```

## Configuration

1. Create a Notion integration at [developers.notion.com](https://developers.notion.com/)
2. Copy your API key
3. Set the environment variable:

```bash
export NOTION_API_KEY=secret_xxxxx
```

Or create a `.env` file:
```
NOTION_API_KEY=secret_xxxxx
```

4. Share pages/databases with your integration in Notion (Settings > Connections)

## Usage

### As MCP Server

```bash
python server.py
```

### Claude Desktop Configuration

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "notion": {
      "command": "python",
      "args": ["/path/to/notion-mcp/server.py"],
      "env": {
        "NOTION_API_KEY": "secret_xxxxx"
      }
    }
  }
}
```

## Available Tools

| Tool | Description |
|------|-------------|
| `notion_search` | Search pages and databases |
| `notion_list_databases` | List all accessible databases |
| `notion_get_database_schema` | Get database properties |
| `notion_query_database` | Query with filters and sorts |
| `notion_create_database_entry` | Create new entry |
| `notion_get_page` | Get page properties |
| `notion_get_page_content` | Get page blocks |
| `notion_create_page` | Create new page |
| `notion_update_page` | Update page properties |
| `notion_archive_page` | Archive a page |
| `notion_append_blocks` | Add content blocks |
| `notion_append_text` | Simple text append |
| `notion_get_users` | List workspace users |
| `notion_whoami` | Get bot info |
| `notion_build_filter` | Helper to build filter JSON |

## Examples

### Query a Database

```python
# Using the MCP tool
notion_query_database(
    database_id="abc123...",
    filter_json='{"property": "Status", "status": {"equals": "Done"}}',
    limit=10
)
```

### Create a Page

```python
notion_create_page(
    parent_id="abc123...",
    title="My New Page",
    parent_type="page_id"
)
```

### Append Content

```python
notion_append_text(
    page_id="abc123...",
    text="Hello World!",
    block_type="paragraph"
)
```

## License

MIT