Basecamp

Interaja com o Basecamp 3 para gerenciar projetos, tarefas e mensagens.

GitHub
101

Documentação

Servidor MCP Basecamp

Python MCP Basecamp License: MIT

Um servidor MCP para Basecamp 3. Ele permite que clientes compatíveis com MCP, como Codex, Cursor e Claude Desktop, leiam e gerenciem projetos do Basecamp por meio de chamadas à API do Basecamp autenticadas via OAuth.

O servidor principal é basecamp_fastmcp.py. Ele usa o SDK Python oficial mcp.server.fastmcp e expõe 79 ferramentas que cobrem projetos, tarefas, quadros de mensagens, campfires, tabelas de cartões, encaminhamentos de caixa de entrada, documentos, uploads, comentários, eventos, webhooks e pesquisa.

O Que Ele Pode Fazer

  • Navegar por projetos do Basecamp e detalhes de projetos.
  • Pesquisar em projetos, tarefas, mensagens, linhas de campfire, comentários, uploads e agendas.
  • Ler e gerenciar listas de tarefas, tarefas, grupos de tarefas e estado de conclusão.
  • Ler e criar mensagens em quadros de mensagens, incluindo rascunhos e categorias.
  • Ler linhas de campfire.
  • Ler e criar comentários.
  • Trabalhar com tabelas de cartões, colunas, cartões e etapas de cartões.
  • Ler encaminhamentos e respostas da caixa de entrada.
  • Ler check-ins diários e respostas.
  • Enviar anexos e inspecionar uploads.
  • Ler e gerenciar documentos, incluindo rascunhos.
  • Listar eventos e gerenciar webhooks.
  • Gerar configuração MCP local para Codex, Cursor e Claude Desktop.

Requisitos

  • Python 3.10 ou mais recente.
  • Uma conta Basecamp 3.
  • Um aplicativo OAuth do Basecamp de https://launchpad.37signals.com/integrations.
  • Um cliente que possa executar servidores MCP locais, como Codex, Cursor ou Claude Desktop.

Se o Python do seu sistema for mais antigo, use uv; ele pode criar um ambiente virtual com uma versão mais recente do Python.

Início Rápido

Clone o repositório e instale as dependências:

git clone https://github.com/georgeantonopoulos/Basecamp-MCP-Server.git
cd Basecamp-MCP-Server

uv venv --python 3.12 venv
source venv/bin/activate
uv pip install -r requirements.txt

Ou, se python já apontar para Python 3.10 ou mais recente:

python setup.py

Crie um arquivo .env a partir do exemplo e preencha com seus detalhes de OAuth do Basecamp:

cp .env.example .env

Valores obrigatórios:

BASECAMP_CLIENT_ID=your-client-id
BASECAMP_CLIENT_SECRET=your-client-secret
BASECAMP_ACCOUNT_ID=your-account-id
USER_AGENT="Your App Name (your@email.com)"

Autentique-se com o Basecamp:

python oauth_app.py

Abra http://localhost:8000 e conclua o fluxo OAuth. O token é armazenado localmente em oauth_tokens.json por padrão.

Configure Seu Cliente MCP

Codex

python generate_codex_config.py
codex mcp get basecamp

Opções úteis:

python generate_codex_config.py --dry-run
python generate_codex_config.py --legacy

O script grava uma entrada de servidor basecamp em ~/.codex/config.toml e a aponta para o ambiente virtual deste checkout e para basecamp_fastmcp.py.

Cursor

python generate_cursor_config.py

Em seguida, reinicie o Cursor e verifique em Configurações -> MCP. O servidor deve aparecer como basecamp.

Claude Desktop

python generate_claude_desktop_config.py

Em seguida, saia completamente e reabra o Claude Desktop. A configuração gerada é gravada em:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: ~/AppData/Roaming/Claude/claude_desktop_config.json
  • Linux: ~/.config/claude-desktop/claude_desktop_config.json

Verifique o Servidor

Execute o servidor FastMCP via stdio e solicite a lista de ferramentas:

printf '%s\n%s\n%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' \
  '{"jsonrpc":"2.0","method":"notifications/initialized","params":{}}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' \
  | python basecamp_fastmcp.py

Execute os testes automatizados:

python -m pytest tests/ -v

Ferramentas Disponíveis

O servidor FastMCP expõe 82 ferramentas.

Projetos e Pesquisa

  • get_projects
  • get_project
  • search_basecamp
  • global_search

Relatórios

  • get_assignable_people — todas as pessoas que podem receber tarefas atribuídas (GET /reports/todos/assigned.json)
  • get_person_assignments — todas as tarefas ativas e pendentes atribuídas a uma pessoa em todos os projetos (GET /reports/todos/assigned/{id}.json, group_by: bucket|date opcional). Prefira esta opção em vez de iterar projetos quando precisar de tudo atribuído a uma única pessoa.
  • get_overdue_todos — todas as tarefas atrasadas em todos os projetos, agrupadas por atraso (GET /reports/todos/overdue.json)

Tarefas

  • get_todolists
  • get_todolist
  • create_todolist
  • update_todolist
  • trash_todolist
  • get_todos
  • get_todo
  • create_todo
  • update_todo
  • delete_todo
  • archive_todo
  • complete_todo
  • uncomplete_todo
  • reposition_todo
  • get_todolist_groups
  • create_todolist_group
  • reposition_todolist_group

Mensagens, Campfires e Check-Ins

  • get_message_board
  • get_messages
  • get_message
  • get_message_categories
  • create_message
  • create_draft_message

Passe publish: false para create_message para criar uma mensagem de rascunho em vez de publicá-la imediatamente. Os agentes também podem chamar create_draft_message diretamente quando a operação pretendida for especificamente criar um rascunho.

  • get_campfire_lines
  • get_daily_check_ins
  • get_question_answers

Comentários

  • get_comments
  • create_comment

Tabelas de Cartões

  • get_card_tables
  • get_card_table
  • get_columns
  • get_column
  • create_column
  • update_column
  • move_column
  • update_column_color
  • put_column_on_hold
  • remove_column_hold
  • watch_column
  • unwatch_column
  • get_cards
  • get_card
  • create_card
  • update_card
  • move_card
  • complete_card
  • uncomplete_card
  • get_card_steps
  • create_card_step
  • get_card_step
  • update_card_step
  • delete_card_step
  • complete_card_step
  • uncomplete_card_step

Encaminhamentos de Caixa de Entrada

  • get_inbox
  • get_forwards
  • get_forward
  • get_inbox_replies
  • get_inbox_reply
  • trash_forward

Documentos, Uploads, Anexos, Eventos e Webhooks

  • create_attachment
  • get_uploads
  • get_upload
  • download_upload — baixa um registro de Upload do vault (Documentos e Arquivos) e retorna seus bytes como conteúdo MCP (ImageContent para tipos MIME de imagem, EmbeddedResource / BlobResourceContents caso contrário). O host MCP encaminha o blob para o modelo, então PDFs, imagens e documentos são lidos nativamente sem uma busca fora de banda.
  • download_attachment — baixa um anexo inline de comentário/mensagem pelo seu content_attachments[].download_url e o retorna como conteúdo MCP. Use esta ferramenta para arquivos incorporados ao corpo de um comentário ou mensagem. Anexos inline são objetos Attachment com seus próprios IDs e não podem ser resolvidos por meio de /uploads/{id} — esse endpoint retorna 404. Para arquivos que são seu próprio registro de Upload em um vault, use download_upload em vez disso.

Compatibilidade de host para download_upload e download_attachment. Ambas as ferramentas retornam blocos de conteúdo MCP. O arquivo só é legível pelo modelo se o host MCP encaminhar ImageContent / EmbeddedResource (BlobResourceContents). Status em junho de 2026:

  • Claude Code (CLI) — totalmente suportado, incluindo application/pdf e outros recursos de blob binário.
  • Claude Desktop / web claude.ai — blocos de conteúdo de imagem funcionam, mas blocos EmbeddedResource que não são de imagem são rejeitados com "Resources of type 'application/pdf' are not currently supported". Os bytes chegam ao host, mas nunca ao modelo. Quando o cliente adicionar suporte, essas ferramentas se tornarão úteis nesses frontends sem alterações no servidor.
  • get_documents
  • get_document
  • create_document
  • create_draft_document

Passe publish: false para create_document para criar um documento de rascunho em vez de publicá-lo imediatamente. Os agentes também podem chamar create_draft_document diretamente quando a operação pretendida for especificamente criar um rascunho.

  • update_document
  • trash_document
  • get_events
  • get_webhooks
  • create_webhook
  • delete_webhook

Exemplos de Prompts

  • "Mostre-me todos os meus projetos do Basecamp."
  • "Pesquise no Basecamp por prazo."
  • "Obtenha as listas de tarefas do projeto 123456."
  • "Crie uma tarefa chamada Revisar PR na lista de tarefas 987654."
  • "Mostre-me as categorias do quadro de mensagens do projeto 123456."
  • "Publique um Anúncio no quadro de mensagens do projeto."
  • "Mostre-me as colunas da tabela de cartões do projeto 123456."
  • "Mova este cartão para a coluna Concluído."
  • "Liste os uploads mais recentes no vault deste projeto."
  • "Baixe a captura de tela anexada àquele comentário para que você possa lê-la."

Arquitetura

Autenticação e Armazenamento de Tokens

O caminho recomendado é OAuth 2.0:

  1. Crie um aplicativo OAuth do Basecamp.
  2. Coloque o ID do cliente, o segredo do cliente, o ID da conta, o URI de redirecionamento e o agente do usuário em .env.
  3. Execute python oauth_app.py.
  4. Conclua o fluxo do navegador em http://localhost:8000.

Por padrão, os tokens OAuth são armazenados em <project>/oauth_tokens.json. Para contêineres, checkouts somente leitura ou volumes de tokens montados, defina BASECAMP_MCP_TOKEN_FILE:

export BASECAMP_MCP_TOKEN_FILE=/var/lib/basecamp-mcp/oauth_tokens.json

Tanto o aplicativo OAuth quanto o servidor MCP leem a mesma variável. token_storage.py expande ~ e variáveis de ambiente neste caminho, cria o diretório pai se necessário e tenta definir as permissões do arquivo de token para 0o600 ao gravar. As permissões do diretório pai continuam sendo sua responsabilidade.

O servidor web OAuth integrado omite strings de consulta de seu log de acesso para que os códigos de autorização de callback não sejam registrados. Se você o executar atrás de outro servidor web ou proxy reverso, configure os logs de acesso desse servidor para omitir strings de consulta também.

Solução de Problemas

Se as ferramentas não aparecerem no seu cliente MCP:

  1. Confirme se o ambiente virtual existe e tem o SDK MCP:

    ./venv/bin/python -c "import mcp; print('MCP available')"

  2. Confirme se .env contém BASECAMP_ACCOUNT_ID.

  3. Execute novamente o gerador de configuração relevante.

  4. Saia completamente e reinicie seu cliente MCP.

Se a autenticação falhar:

python oauth_app.py

Em seguida, abra http://localhost:8000 e conclua o fluxo OAuth do Basecamp novamente.

Para Claude Desktop no macOS, os logs MCP geralmente ficam em:

~/Library/Logs/Claude/

Notas de Segurança

  • Não faça commit de .env ou oauth_tokens.json.
  • Use um USER_AGENT descritivo que inclua informações de contato, pois o Basecamp espera que os clientes de API se identifiquem.
  • Mantenha os arquivos de token em armazenamento local ou com permissões adequadas.
  • Este servidor foi projetado para uso local com clientes MCP. Revise o código e o modelo de implantação antes de expô-lo em uma rede.

Licença

MIT. Consulte LICENSE.

Histórico de Estrelas

Star History Chart