grc-evidence-mcp — Guía de construcción paso a paso

Construye un MCP real de recopilación de evidencia GRC de solo lectura en Python, conéctalo a Claude Desktop, pruébalo contra tu propio repositorio de GitHub y, opcionalmente, añade captura de evidencia visual con Playwright.

Esta guía está escrita para que puedas completar la construcción incluso si nunca has construido un MCP antes. Si ya te sientes cómodo con Python, terminales, APIs o Claude Code, puedes avanzar más rápido y usar las explicaciones solo cuando las necesites.

Repositorio terminado: [ENLACE AL REPOSITORIO DE GITHUB]

Lo que estás construyendo

Al final, tu MCP podrá:

1. Listar las fuentes de evidencia que conoce.

2. Recopilar evidencia real de GitHub para la protección de ramas y CODEOWNERS.

3. Mapear esa evidencia a referencias de control.

4. Almacenar la evidencia completa localmente en SQLite y devolver solo un collection_id opaco a Claude.

5. Recuperar una colección de evidencia almacenada por su id.

6. Opcionalmente, capturar una captura de pantalla real de una página web con Playwright y almacenarla como evidencia visual.

La regla de diseño para todo el proyecto es simple: leer evidencia DEL sistema auditado; escribir evidencia solo EN tu zona de aterrizaje local. Nunca modifiques el sistema auditado.

Elige tu ritmo

Puedes construir esto en una sola sesión siguiendo la guía de principio a fin, o distribuirlo en cinco días.

Related MCP server: Change Trace MCP

Ruta de 5 días

Día 1 — Configura Claude Code y construye la base

Objetivo: Obtener un proyecto MCP funcional con almacenamiento de evidencia local y una herramienta visible.

Acciones:

• Instala Claude Code.

• Crea una carpeta de proyecto vacía.

• Inicia Claude Code dentro de la carpeta.

• Pega el Prompt 1.

• Deja que Claude Code cree el proyecto Python, el StateStore respaldado por SQLite y la herramienta list_evidence_sources.

• Ejecuta el proyecto localmente y resuelve cualquier error de instalación antes de continuar.

Listo cuando: Claude Code pueda ejecutar el MCP y list_evidence_sources exista.

Día 2 — Conecta el MCP a Claude Desktop

Objetivo: Hacer que Claude Desktop vea el MCP que construiste.

Acciones:

• Pega el Prompt 2 en Claude Code.

• Deja que Claude Code actualice la configuración del MCP de Claude Desktop usando la ruta completa del servidor.

• Cierra completamente Claude Desktop y vuelve a abrirlo.

• Abre un nuevo chat y verifica el icono de herramientas/martillo.

Listo cuando: list_evidence_sources aparezca como una herramienta en Claude Desktop.

Día 3 — Añade la fuente de evidencia real de GitHub

Objetivo: Reemplazar el pensamiento de "solo demostración" con una llamada API real de solo lectura.

Acciones:

• Pega el Prompt 3.

• Crea un token de acceso personal de grano fino de GitHub con solo los permisos requeridos para esta construcción.

• Copia .env.example a .env y añade el token allí.

• Nunca pegues el token en el chat de Claude Desktop o Claude Code.

• Reinicia Claude Desktop después de los cambios de entorno/configuración.

Listo cuando: el MCP tenga una herramienta collect_evidence funcional y tu token esté disponible para el servidor.

Día 4 — Prueba, recupera e inspecciona evidencia real

Objetivo: Demostrar que tu MCP funciona contra un repositorio que realmente controlas.

Acciones:

• Ejecuta el prompt de prueba de GitHub contra tu propio repositorio.

• Copia el collection_id devuelto.

• Pide a Claude Desktop que recupere esa colección.

• Revisa los hallazgos de protección de ramas y CODEOWNERS.

• Lee la sección de limitación 404 antes de tratar un resultado "ausente" como una brecha de control.

Listo cuando: hayas recuperado un registro almacenado producido por una llamada API de GitHub en vivo.

Día 5 — Añade evidencia visual, limpia y publica

Objetivo: Convertir el proyecto en algo listo para un portafolio.

Acciones:

• Instala el extra opcional de Playwright y Chromium.

• Añade o verifica collect_visual_evidence.

• Captura una captura de pantalla de una página real a la que estés autorizado a acceder.

• Recupera la colección de evidencia de captura de pantalla e inspecciona sus metadatos.

• Limpia tu README, confirma que .env está ignorado y sube el proyecto a GitHub.

• Si estás participando en el desafío, envía tu repositorio usando las instrucciones del desafío.

Listo cuando: tu repositorio explique qué hace el MCP, cómo ejecutarlo, cuáles son sus limitaciones e incluya sin secretos.

Antes de comenzar

Necesitas:

• Una computadora con terminal.

• Una cuenta de Claude que pueda usar Claude Code.

• Claude Desktop para la parte de herramientas de escritorio del tutorial.

• Acceso a una cuenta de GitHub y al menos un repositorio que puedas probar.

• Python 3.10 o más reciente.

• Node.js si tu máquina no lo tiene ya.

Si eres completamente nuevo

No necesitas entender cada línea de Python antes de comenzar. Tu trabajo durante esta construcción es entender de qué es responsable cada componente, qué datos entran, qué regresa y dónde están los límites de seguridad. Cuando Claude Code cree o cambie un archivo, pídele que te explique el archivo en inglés sencillo antes de continuar si no estás seguro.

Si eres más técnico

Puedes inspeccionar los archivos generados, ejecutar pruebas entre cada prompt y desafiar a Claude Code sobre las decisiones de implementación. El repositorio terminado es una implementación de referencia, no un requisito de que cada archivo se vea idéntico.

Paso 1 — Instala Claude Code

Ejecuta:

npm install -g @anthropic-ai/claude-code

Si eso falla porque falta Node.js, instala Node.js y luego ejecuta el comando nuevamente.

Inicia Claude Code:

claude

La primera ejecución te pedirá que inicies sesión.

Esta construcción está intencionalmente orientada a la terminal. No necesitas un editor separado para completarla.

Paso 2 — Crea tu carpeta de proyecto

mkdir my-evidence-mcp
cd my-evidence-mcp
claude

De ahora en adelante, pega los prompts de construcción en Claude Code en orden.

Prompt 1 — Construye la base

Help me build a small MCP server in Python called grc-evidence-mcp, using
FastMCP over stdio, that I'll connect to Claude Desktop.

Purpose: read-only compliance evidence collection. It reads evidence FROM
systems and writes evidence TO a local landing zone — it must never modify
the audited system itself.

Build the foundation first, not real sources yet:

1. A StateStore class backed by SQLite — save(record) returns an opaque id,
   get(id) returns the record back. That id is the only handle anything
   else gets to a stored record.
2. One tool: list_evidence_sources — returns available sources and flags
   which ones are just stubs for now. Register one stub source so the
   list isn't empty.

Get this running and visible as a tool in Claude Code before we add
anything real.

Lo que este paso te enseña

El StateStore separa la conversación del registro de evidencia completo. En lugar de entregar toda la evidencia recopilada directamente al modelo, el servidor la almacena localmente y le da a Claude un id. Claude puede pasar ese id más tarde sin tener que reproducir la evidencia en sí.

Punto de control

Antes de continuar, pide a Claude Code que te muestre:

• dónde comienza el servidor MCP,

• dónde escribe datos StateStore,

• dónde está registrado list_evidence_sources,

• y el comando que usó para confirmar que el servidor se inicia correctamente.

Prompt 2 — Conéctalo a Claude Desktop

Add this server to my Claude Desktop config at ~/Library/Application
Support/Claude/claude_desktop_config.json. Use the full path to the
server, not just the command name, so it doesn't rely on my terminal's
PATH.

Esta ruta es la ruta de macOS utilizada en el tutorial. Si estás en otro sistema operativo, pide a Claude Code que localice el archivo de configuración del MCP de Claude Desktop para tu sistema operativo antes de que edite algo.

Usa la ruta completa al comando del servidor. Claude Desktop no necesariamente hereda el mismo PATH que tu terminal.

Luego cierra completamente Claude Desktop y vuelve a abrirlo. Un cierre normal de ventana o una recarga puede no recargar la configuración del MCP.

Abre un nuevo chat y verifica el icono de herramientas/martillo. Deberías ver list_evidence_sources.

Si no ves la herramienta

Verifica en este orden:

1. ¿Guardó Claude Code la configuración en el archivo de configuración correcto de Claude Desktop?

2. ¿La configuración usa una ruta completa de ejecutable/servidor?

3. ¿Se inicia el MCP correctamente desde tu terminal?

4. ¿Cerraste completamente y reabriste Claude Desktop?

5. ¿Abriste un nuevo chat después de reiniciar?

No continúes al paso de GitHub hasta que la herramienta base sea visible.

Prompt 3 — Añade la fuente real de GitHub

Now build the first real source: GitHub.

Add a collect_evidence(source_name, params) tool that, for source_name=
"github", checks branch protection status and CODEOWNERS presence on a
repo I specify (owner/repo/branch), using my own GitHub token
(read-only — Administration:read and Contents:read, nothing else).

Map each result to a control reference:
- branch protection present → SOC2-CC8.1, ISO27001-A.8.32
- CODEOWNERS present → SOC2-CC8.1, ISO27001-A.5.3

Return a collection_id from StateStore, not the raw evidence directly.
I want to run this against a real repo of mine and see actual results,
not sample data.

Crea el token de GitHub

Crea un token de acceso personal de grano fino para el repositorio que planeas probar. Otorga solo:

• Administración: lectura

• Contenido: lectura

No reutilices un token más amplio solo porque ya tienes uno.

Pon el token en .env

El repositorio terminado incluye .env.example. Cópialo:

cp .env.example .env

Luego establece:

GITHUB_TOKEN=your_token_value_here

El repositorio terminado carga este archivo .env cuando el recopilador de GitHub se inicia.

Nunca pegues el token real en un mensaje de Claude Desktop o Claude Code. El token pertenece al entorno, no a la conversación. También mantén .env en .gitignore para que nunca se confirme.

Después de cambiar el token/entorno, reinicia completamente Claude Desktop.

Paso 4 — Prueba contra tu propio repositorio

En Claude Desktop, pregunta:

Check branch protection and CODEOWNERS on [your-username]/[your-repo],
branch main.

Esto debería hacer una llamada API real de GitHub contra el repositorio que nombraste.

La herramienta debería devolver un collection_id, no el registro bruto completo.

Luego pregunta:

Get the evidence collection with id [collection_id].

Ahora deberías ver el registro de evidencia almacenado.

Qué inspeccionar

Busca:

• nombre del repositorio y de la rama,

• resultado de protección de ramas,

• resultado de CODEOWNERS,

• referencias de control mapeadas,

• detalles de evidencia/estado subyacentes,

• marca de tiempo de la colección.

Este es el punto donde el proyecto se convierte en algo más que una demostración: has recopilado y recuperado evidencia de un sistema real que controlas.

Limitación importante — Los 404 de GitHub son ambiguos

GitHub puede devolver un 404 cuando la protección de ramas no está configurada, pero un 404 también puede ocurrir porque el repositorio/rama no se puede encontrar o el llamador no tiene suficiente acceso para confirmar la configuración.

El recopilador de GitHub actual conserva los detalles de la respuesta, pero aún registra un resultado 404 como present: false. No trates automáticamente eso como una brecha de control confirmada. Un revisor humano debe verificar si el resultado significa "no configurado" o "no se pudo confirmar".

Esa distinción es parte de la buena ingeniería de GRC: "no" y "no sé" no son el mismo hallazgo.

Bono — Añade evidencia visual con Playwright

Esto es opcional. El MCP principal funciona sin ello.

El repositorio terminado usa Playwright con Chromium sin cabeza. No depende de la extensión Claude for Chrome.

Instala el paquete opcional y el navegador:

pip install -e ".[screenshot]"
playwright install chromium

Si estás construyendo desde prompts, usa:

Add a tool collect_visual_evidence(url, subject) that opens the given URL
in headless Chromium via Playwright, captures a full-page screenshot, and
stores it the same way collect_evidence does — save the result to
StateStore, return only a collection_id, never the raw image bytes.

Classify the result conservatively: a successful page load can be stored
as present; a 401/403 authentication wall, a 404, or a navigation failure
must not be treated as proof that a control is missing. Record those as
indeterminate or error as appropriate. Burn a timestamp using the local
machine timezone into the screenshot metadata so a reviewer knows when
it was captured.

Luego intenta:

Capture visual evidence of https://github.com/[your-username]/[your-repo]/settings/branches.

La herramienta de captura de pantalla almacena el PNG en el directorio local de capturas de pantalla del MCP y almacena sus metadatos en StateStore. Devuelve un nuevo collection_id para ese registro de evidencia de captura de pantalla.

Una captura de pantalla muestra cómo se veía la página en el momento de la captura. No es prueba por sí misma de que un control sea efectivo. La implementación trata intencionalmente los muros de autenticación y los 404 como indeterminados en lugar de fallas de control. La captura visual es específica de la página y no toma una captura de pantalla de tu escritorio local.

Lo que contiene el repositorio terminado

• grc_evidence_mcp/store.py — StateStore respaldado por SQLite con ids opacos.

• grc_evidence_mcp/server.py — registro de herramientas MCP y flujo de trabajo de almacenamiento de evidencia.

• grc_evidence_mcp/github.py — recopilador de evidencia de API de GitHub de solo lectura.

• grc_evidence_mcp/screenshot.py — recopilador de capturas de pantalla opcional con Playwright.

• .env.example — plantilla segura para la variable del token de GitHub.

• .gitignore — evita que secretos locales como .env se confirmen.

• pyproject.toml — dependencias de Python y extra opcional de captura de pantalla.

Herramientas principales:

• list_evidence_sources

• collect_evidence

• get_evidence_collection

Herramienta de bono opcional:

• collect_visual_evidence

Solución de problemas por síntoma

Comando claude no encontrado

Instala Node.js si es necesario y vuelve a ejecutar la instalación de npm de Claude Code.

La herramienta MCP no aparece en Claude Desktop

Verifica la ubicación de la configuración y la ruta completa del servidor, confirma que el servidor se inicia en la terminal, reinicia completamente Claude Desktop y luego abre un nuevo chat.

GITHUB_TOKEN is not set

Confirma que .env existe en la raíz del proyecto, contiene GITHUB_TOKEN=... y que estás ejecutando el proyecto actualizado que carga .env. Reinicia Claude Desktop después de cambiar el entorno/configuración.

GitHub devuelve 401

El token es inválido, ha expirado o no se está leyendo correctamente.

GitHub devuelve 403

El token/cuenta probablemente no tiene el acceso de lectura requerido al repositorio o a la configuración.

GitHub devuelve 404

No lo llames inmediatamente una falla de control. Confirma el repositorio, la rama, el acceso del token y la respuesta subyacente de GitHub.

Playwright no está instalado

Ejecuta:

pip install -e ".[screenshot]"
playwright install chromium

La captura de pantalla muestra una página de inicio de sesión

Eso sigue siendo una captura de pantalla real, pero no prueba el estado del control. Trátalo como indeterminado y autentícate adecuadamente antes de intentarlo nuevamente si estás autorizado a hacerlo.

Antes de publicar tu repositorio

• Asegúrate de que .env no se suba al repositorio.

• Busca en el repositorio tu token u otros secretos.

• Mantén la sección de limitaciones del README.

• Explica que las llamadas a GitHub son de solo lectura.

• Explica que las capturas de pantalla muestran el estado de la página en el momento de la captura, no la eficacia del control.

• Incluye suficientes instrucciones de configuración para que otra persona pueda reproducir la compilación.

• Usa tu propio repositorio en las capturas de pantalla/ejemplos, o redacta cualquier cosa que no debas publicar.

Para el desafío

Para celebrar los 100 suscriptores: un sorteo de $306 — un año de Claude Pro más un año de membresía del GRC Engineering Club.

Para participar:

1. Estar suscrito.

2. Construir el MCP.

3. Enviar el repositorio de GitHub de lo que construiste.

Se seleccionará un ganador mediante sorteo aleatorio entre las participaciones que cumplan los requisitos. Etiqueta tu proyecto con Built with BuildinginGRC.

Verificación final de aprendizaje

Antes de dar el proyecto por completo, deberías poder explicar estas cinco cosas con tus propias palabras:

1. Por qué el MCP es de solo lectura respecto al sistema auditado.

2. Por qué el servidor almacena evidencia y devuelve un collection_id en lugar de devolverlo todo directamente.

3. Por qué el token de GitHub debería tener solo los permisos que necesita el recopilador.

4. Por qué un 404 o una pantalla de inicio de sesión no son automáticamente prueba de que falta un control.

5. Qué demuestra un resultado de API frente a qué demuestra una captura de pantalla.

Si puedes explicar todo eso, hiciste más que copiar un proyecto: entiendes las decisiones de ingeniería de GRC que hay detrás.