Notion Agent Server

MCP Notion Agent Server

Servidor MCP (Model Context Protocol) que integra o VS Code Copilot com o Notion, permitindo que um agente de IA crie, conclua e liste tarefas diretamente em um banco de dados do Notion.

Este projeto foi construído com Python, FastMCP e Notion API, expondo o servidor via ASGI + SSE, conforme o padrão MCP.

📌 Visão Geral

Arquitetura simplificada:

VS Code Copilot (LLM)
        ↓
       MCP
        ↓
   FastMCP Server (server.py)
        ↓
   Notion API

O servidor atua como um adaptador semântico, traduzindo intenções do LLM em ações reais no Notion.

📦 Requisitos

• Python 3.12+
• Poetry
• Conta no Notion
• Um banco de dados no Notion com as colunas:

* Name (Title) * Status (Select) * Prazo (Date)

• VS Code com GitHub Copilot habilitado

🚀 Instalação

1️⃣ Clone o repositório

git clone https://github.com/EVANGELISTA-RIBEIRO/mcp-notion-agent-server.git
cd mcp-notion-agent-server

2️⃣ Instale as dependências

poetry install

⚙️ Configuração

1️⃣ Crie o arquivo .env

Na raiz do projeto, crie um arquivo chamado .env:

NOTION_TOKEN=seu_token_do_notion
NOTION_DATABASE_ID=seu_database_id

🔐 Importante: nunca versionar este arquivo.

2️⃣ Estrutura esperada do banco de dados Notion

▶️ Execução do Servidor MCP

Execute o servidor via Uvicorn:

poetry run python -m uvicorn server:asgi_app --reload --host 0.0.0.0 --port 8000

Saída esperada:

Uvicorn running on http://0.0.0.0:8000
Application startup complete.

O endpoint SSE estará disponível em:

http://localhost:8000/sse

🧪 Testes no VS Code (Copilot + MCP)

1️⃣ Configure o MCP no VS Code

No VS Code, abra o arquivo de configuração do Copilot MCP (conforme a documentação oficial):

{
  "mcpServers": {
    "notion-agent": {
      "url": "http://localhost:8000/sse"
    }
  }
}

2️⃣ Exemplos de uso com o Copilot

No editor, você pode pedir coisas como:

• "Crie uma nova tarefa no Notion chamada Estudar MCP com prazo amanhã"
• "Liste minhas tarefas pendentes"
• "Conclua a tarefa com ID xxx"

O Copilot irá:

1. Interpretar sua intenção
2. Chamar as tools MCP
3. Executar ações reais no Notion

🛠️ Tools Disponíveis

🔹 criar_tarefa

Cria uma nova tarefa no banco de dados do Notion.

Campos:

• titulo (string)
• descricao (string)
• prazo (date, opcional)

🔹 concluir_tarefa

Atualiza o status de uma tarefa existente para Concluído.

Campos:

• page_id (string)
• status (string, padrão: Concluído)

📚 Resources Disponíveis

🔹 notion://tarefas/pendentes

Lista todas as tarefas que não estão concluídas, ordenadas por prazo.

🧠 Observações Importantes

• Este projeto não é um backend REST tradicional
• Ele existe exclusivamente para interação entre LLMs e serviços externos
• O formato textual das respostas é intencionalmente simples para melhor interpretação pelo LLM

✨ Autor

João Victor Evangelista Lopes Ribeiro

📍 Brasília - DF, Brasil

💻 Desenvolvedor Backend / Full Stack

📬 Contatos

• GitHub: https://github.com/EVANGELISTA-RIBEIRO

• LinkedIn: https://www.linkedin.com/in/joaoevanglopes/

• Email: joaoevangelistalopes.ti@gmail.com

Este projeto foi desenvolvido com foco em aprendizado profundo, boas práticas de arquitetura e integração de servidores MCP com o GitHub Copilot e Notion.