Servidor MCP de Notion
Implementación de servidor del Protocolo de Contexto de Modelo (MCP) para la integración con Notion, que proporciona una interfaz estandarizada para interactuar con la API de Notion. Compatible con Claude Desktop y otros clientes MCP.
Características
- Listar y consultar bases de datos de Notion
- Crear y actualizar páginas
- Buscar en el espacio de trabajo de Notion
- Obtener detalles de la base de datos y bloquear a los niños
- Soporte completo de async/await con httpx
- Tipo seguro con modelos Pydantic v2
- Manejo adecuado de errores con registro detallado
- Compatibilidad con MCP 1.6.0
Instalación
- Clonar el repositorio:
git clone https://github.com/ccabanillas/notion-mcp.git
cd notion-mcp
- Cree un entorno virtual e instale dependencias (usando uv):
uv venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
uv pip install -e .
Alternativamente, utilizando venv estándar:
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
pip install -e .
- Cree un archivo
.env en la raíz del proyecto:
NOTION_API_KEY=your_notion_integration_token
Uso
- Pruebe el servidor (debería funcionar sin errores):
- Para usarlo con Claude Desktop, ajuste su archivo
claude_desktop_config.json (ubicado en ~/Library/Application Support/Claude/claude_desktop_config.json en macOS):
{
"servers": {
"notion-mcp": {
"command": "/Users/username/Projects/notion-mcp/.venv/bin/python",
"args": ["-m", "notion_mcp"],
"cwd": "/Users/username/Projects/notion-mcp"
}
}
}
Asegúrese de reemplazar /Users/username/ con la ruta de su directorio de inicio real.
Desarrollo
Estructura del proyecto
notion-mcp/
├── src/
│ └── notion_mcp/
│ ├── models/
│ │ ├── __init__.py
│ │ └── notion.py # Pydantic models for Notion objects
│ ├── __init__.py
│ ├── __main__.py # Entry point
│ ├── client.py # Notion API client
│ └── server.py # MCP server implementation
├── .env # Environment variables (add your Notion API key here)
├── .gitignore
├── pyproject.toml # Project dependencies
└── README.md
Ejecución de pruebas
Configuración
El servidor requiere un token de integración de Notion. Para configurarlo:
- Vaya a https://www.notion.so/my-integrations
- Cree una nueva integración con capacidades adecuadas (lectura/escritura según sea necesario)
- Copiar el token de integración
- Agreguelo a su archivo
.env en el directorio raíz del proyecto:
NOTION_API_KEY=your_notion_integration_token
- Comparte tus bases de datos de Notion con la integración (desde el menú "Compartir" de la base de datos)
Contribuyendo
- Bifurcar el repositorio
- Crea tu rama de funciones (
git checkout -b feature/amazing-feature ) - Confirme sus cambios (
git commit -m 'Add some amazing feature' ) - Empujar a la rama (
git push origin feature/amazing-feature ) - Abrir una solicitud de extracción
Licencia
Licencia MIT - Úselo bajo su propio riesgo
Solución de problemas
Problemas comunes
- Errores de conexión : asegúrese de que su clave API de Notion sea correcta y tenga acceso a Internet
- Errores de permisos : asegúrese de que su integración tenga acceso a las bases de datos a las que intenta acceder
- Integración de Claude Desktop : si Claude Desktop no se conecta, verifique que su ruta de configuración sea correcta y que el servidor se esté ejecutando sin iniciar sesión en stdout
Expresiones de gratitud
- Creado para funcionar con Claude Desktop y otros clientes MCP
- Utiliza la API de Notion (última versión compatible: 22/02/2022)
- Se mantiene la compatibilidad con MCP 1.6.0
- Un agradecimiento especial a danhilse , hice referencia a su proyecto notion-mcp-server.