Basecamp

Interactúa con Basecamp 3 para gestionar proyectos, tareas pendientes y mensajes.

GitHub
101

Documentación

Servidor MCP de Basecamp

Python MCP Basecamp License: MIT

Un servidor MCP para Basecamp 3. Permite que clientes compatibles con MCP, como Codex, Cursor y Claude Desktop, lean y gestionen proyectos de Basecamp mediante llamadas a la API de Basecamp autenticadas con OAuth.

El servidor principal es basecamp_fastmcp.py. Utiliza el SDK oficial de Python mcp.server.fastmcp y expone 79 herramientas que cubren proyectos, tareas pendientes, foros de mensajes, campfires, tableros de tarjetas, reenvíos de bandeja de entrada, documentos, cargas, comentarios, eventos, webhooks y búsqueda.

Qué Puede Hacer

  • Explorar proyectos de Basecamp y sus detalles.
  • Buscar en proyectos, tareas pendientes, mensajes, líneas de campfire, comentarios, cargas y horarios.
  • Leer y gestionar listas de tareas, tareas pendientes, grupos de tareas y su estado de finalización.
  • Leer y crear mensajes en foros de mensajes, incluidos borradores y categorías.
  • Leer líneas de campfire.
  • Leer y crear comentarios.
  • Trabajar con tableros de tarjetas, columnas, tarjetas y pasos de tarjetas.
  • Leer reenvíos y respuestas de la bandeja de entrada.
  • Leer check-ins diarios y sus respuestas.
  • Subir archivos adjuntos e inspeccionar cargas.
  • Leer y gestionar documentos, incluidos borradores.
  • Listar eventos y gestionar webhooks.
  • Generar configuración local de MCP para Codex, Cursor y Claude Desktop.

Requisitos

  • Python 3.10 o superior.
  • Una cuenta de Basecamp 3.
  • Una aplicación OAuth de Basecamp desde https://launchpad.37signals.com/integrations.
  • Un cliente que pueda ejecutar servidores MCP locales, como Codex, Cursor o Claude Desktop.

Si el Python de tu sistema es más antiguo, usa uv; puede crear un entorno virtual con una versión más reciente de Python.

Inicio Rápido

Clona el repositorio e instala las dependencias:

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

O, si python ya apunta a Python 3.10 o superior:

python setup.py

Crea un archivo .env a partir del ejemplo y completa tus datos de OAuth de Basecamp:

cp .env.example .env

Valores requeridos:

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)"

Autentícate con Basecamp:

python oauth_app.py

Abre http://localhost:8000 y completa el flujo de OAuth. El token se almacena localmente en oauth_tokens.json de forma predeterminada.

Configura Tu Cliente MCP

Codex

python generate_codex_config.py
codex mcp get basecamp

Opciones útiles:

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

El script escribe una entrada de servidor basecamp en ~/.codex/config.toml y la apunta al entorno virtual de este checkout y a basecamp_fastmcp.py.

Cursor

python generate_cursor_config.py

Luego reinicia Cursor y revisa Configuración -> MCP. El servidor debería aparecer como basecamp.

Claude Desktop

python generate_claude_desktop_config.py

Luego cierra y vuelve a abrir Claude Desktop por completo. La configuración generada se escribe en:

  • 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

Verifica El Servidor

Ejecuta el servidor FastMCP a través de stdio y solicita su lista de herramientas:

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

Ejecuta las pruebas automatizadas:

python -m pytest tests/ -v

Herramientas Disponibles

El servidor FastMCP expone 82 herramientas.

Proyectos Y Búsqueda

  • get_projects
  • get_project
  • search_basecamp
  • global_search

Informes

  • get_assignable_people — todas las personas a las que se les pueden asignar tareas pendientes (GET /reports/todos/assigned.json)
  • get_person_assignments — todas las tareas pendientes activas asignadas a una persona en todos los proyectos (GET /reports/todos/assigned/{id}.json, group_by: bucket|date opcional). Prefiere esto sobre iterar proyectos cuando necesites todo lo asignado a una sola persona.
  • get_overdue_todos — todas las tareas pendientes vencidas en todos los proyectos, agrupadas por retraso (GET /reports/todos/overdue.json)

Tareas Pendientes

  • 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

Mensajes, Campfires Y Check-Ins

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

Pasa publish: false a create_message para crear un mensaje borrador en lugar de publicarlo inmediatamente. Los agentes también pueden llamar a create_draft_message directamente cuando la operación prevista sea específicamente crear un borrador.

  • get_campfire_lines
  • get_daily_check_ins
  • get_question_answers

Comentarios

  • get_comments
  • create_comment

Tableros De Tarjetas

  • 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

Reenvíos De Bandeja De Entrada

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

Documentos, Cargas, Archivos Adjuntos, Eventos Y Webhooks

  • create_attachment
  • get_uploads
  • get_upload
  • download_upload — descarga un registro de Upload de vault (Docs & Files) y devuelve sus bytes como contenido MCP (ImageContent para tipos MIME de imagen, EmbeddedResource / BlobResourceContents en caso contrario). El host MCP reenvía el blob al modelo, por lo que PDFs, imágenes y documentos se leen de forma nativa sin una búsqueda fuera de banda.
  • download_attachment — descarga un archivo adjunto de comentario/mensaje en línea por su content_attachments[].download_url y lo devuelve como contenido MCP. Úsalo para archivos incrustados en el cuerpo de un comentario o mensaje. Los archivos adjuntos en línea son objetos Attachment con sus propios IDs y no se pueden resolver mediante /uploads/{id} — ese endpoint devuelve 404. Para archivos que son su propio registro de Upload en un vault, usa download_upload en su lugar.

Compatibilidad del host para download_upload y download_attachment. Ambas herramientas devuelven bloques de contenido MCP. El archivo solo es legible por el modelo si el host MCP reenvía ImageContent / EmbeddedResource (BlobResourceContents). Estado a junio de 2026:

  • Claude Code (CLI) — totalmente compatible, incluidos application/pdf y otros recursos de blob binarios.
  • Claude Desktop / web de claude.ai — los bloques de contenido de imagen funcionan, pero los bloques EmbeddedResource que no son de imagen se rechazan con "Resources of type 'application/pdf' are not currently supported". Los bytes llegan al host pero nunca al modelo. Una vez que el cliente agregue soporte, estas herramientas serán útiles en esos frontends sin cambios en el servidor.
  • get_documents
  • get_document
  • create_document
  • create_draft_document

Pasa publish: false a create_document para crear un documento borrador en lugar de publicarlo inmediatamente. Los agentes también pueden llamar a create_draft_document directamente cuando la operación prevista sea específicamente crear un borrador.

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

Ejemplos De Indicaciones

  • "Muéstrame todos mis proyectos de Basecamp."
  • "Busca en Basecamp la fecha límite."
  • "Obtén las listas de tareas pendientes del proyecto 123456."
  • "Crea una tarea pendiente llamada Revisar PR en la lista de tareas 987654."
  • "Muéstrame las categorías del foro de mensajes del proyecto 123456."
  • "Publica un Anuncio en el foro de mensajes del proyecto."
  • "Muéstrame las columnas del tablero de tarjetas del proyecto 123456."
  • "Mueve esta tarjeta a la columna Hecho."
  • "Lista las últimas cargas en el vault de este proyecto."
  • "Descarga la captura de pantalla adjunta a ese comentario para que puedas leerla."

Arquitectura

Autenticación Y Almacenamiento De Tokens

La ruta recomendada es OAuth 2.0:

  1. Crea una aplicación OAuth de Basecamp.
  2. Coloca el ID de cliente, el secreto de cliente, el ID de cuenta, la URI de redirección y el agente de usuario en .env.
  3. Ejecuta python oauth_app.py.
  4. Completa el flujo del navegador en http://localhost:8000.

De forma predeterminada, los tokens OAuth se almacenan en <project>/oauth_tokens.json. Para contenedores, checkouts de solo lectura o volúmenes de tokens montados, establece BASECAMP_MCP_TOKEN_FILE:

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

Tanto la aplicación OAuth como el servidor MCP leen la misma variable. token_storage.py expande ~ y las variables de entorno en esta ruta, crea el directorio principal si es necesario e intenta establecer los permisos del archivo de token a 0o600 al escribir. Los permisos del directorio principal siguen siendo tu responsabilidad.

El servidor web OAuth integrado omite las cadenas de consulta de su registro de acceso para que los códigos de autorización de devolución de llamada no se registren. Si lo ejecutas detrás de otro servidor web o proxy inverso, configura los registros de acceso de ese servidor para omitir también las cadenas de consulta.

Solución De Problemas

Si las herramientas no aparecen en tu cliente MCP:

  1. Confirma que el entorno virtual existe y tiene el SDK de MCP:

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

  2. Confirma que .env contiene BASECAMP_ACCOUNT_ID.

  3. Vuelve a ejecutar el generador de configuración correspondiente.

  4. Cierra y reinicia tu cliente MCP por completo.

Si la autenticación falla:

python oauth_app.py

Luego abre http://localhost:8000 y completa el flujo de OAuth de Basecamp nuevamente.

Para Claude Desktop en macOS, los registros de MCP suelen estar en:

~/Library/Logs/Claude/

Notas De Seguridad

  • No confirmes .env ni oauth_tokens.json.
  • Usa un USER_AGENT descriptivo que incluya información de contacto, ya que Basecamp espera que los clientes de API se identifiquen.
  • Mantén los archivos de token en almacenamiento local o con permisos adecuados.
  • Este servidor está diseñado para uso local con clientes MCP. Revisa el código y el modelo de implementación antes de exponerlo en una red.

Licencia

MIT. Consulta LICENSE.

Historial De Estrellas

Star History Chart