Papierkram

Servidor MCP de Papierkram

Un servidor MCP (Model Context Protocol) para la API de contabilidad de Papierkram.de. Permite a los asistentes de IA gestionar facturas, gastos, contactos, proyectos, seguimiento de tiempo y más directamente en tu cuenta de Papierkram.

Características

• 56 herramientas que cubren toda la API v1 de Papierkram
• Instalación vía npm: ejecuta directamente con npx papierkram-mcp-server — sin necesidad de clonar
• Dos transportes: stdio (para Claude Desktop, Cursor, Claude Code) y HTTP/SSE (para n8n, integraciones personalizadas)
• Listo para Docker para un despliegue autohospedado sencillo
• TypeScript con validación de esquemas Zod en todos los parámetros

Resumen de Herramientas

Área	Operaciones	Cantidad
Contactos	Empresas y personas de contacto: listar, obtener, crear, actualizar, eliminar	10
Facturas	listar, obtener, crear, actualizar, eliminar, cancelar, archivar, enviar, descargar PDF	9
Presupuestos	listar, obtener, crear, actualizar, eliminar, enviar, descargar PDF	7
Gastos	listar, obtener, crear, actualizar, eliminar	5
Proyectos	listar, obtener, crear, actualizar, eliminar, archivar, desarchivar	7
Seguimiento de Tiempo	listar, obtener, crear, actualizar, eliminar	5
Tareas	listar, obtener, crear, actualizar, eliminar	5
Banca	listar, obtener conexiones bancarias y transacciones (solo lectura)	4
Cuenta	Información de cuenta, condiciones de pago, propuestas	4

Inicio Rápido

Requisitos previos

• Node.js 20+ (o Docker)
• Una cuenta de Papierkram.de con acceso a la API

Obtén tu Clave de API

Ve a Papierkram > Einstellungen > API y crea una clave de API.

Opción A: npm (recomendado)

Sin necesidad de clonar — ejecuta directamente con npx:

npx papierkram-mcp-server

O instálalo globalmente:

npm install -g papierkram-mcp-server
papierkram-mcp-server

El servidor usa stdio por defecto; configura PAPIERKRAM_API_KEY y PAPIERKRAM_SUBDOMAIN en tu entorno o en la configuración de tu cliente MCP (ver Uso).

Opción B: Docker (HTTP/SSE autohospedado)

git clone https://github.com/Wagner-Emden-IT-Services/papierkram-mcp-server.git
cd papierkram-mcp-server
cp .env.example .env
# Edit .env with your API key and subdomain
docker compose up -d

El servidor HTTP/SSE estará disponible en http://localhost:3001/sse.

Opción C: Node.js desde el código fuente

git clone https://github.com/Wagner-Emden-IT-Services/papierkram-mcp-server.git
cd papierkram-mcp-server
npm install
cp .env.example .env
# Edit .env with your API key and subdomain
npm run build

Configuración

Crea un archivo .env (o cópialo de .env.example):

PAPIERKRAM_API_KEY=your-api-key-here
PAPIERKRAM_SUBDOMAIN=your-subdomain
PORT=3001  # optional, only for HTTP/SSE mode

Tu subdominio es la parte antes de .papierkram.de en tu URL de Papierkram.

Uso

Claude Desktop

Añade a tu claude_desktop_config.json:

{
  "mcpServers": {
    "papierkram": {
      "command": "npx",
      "args": ["-y", "papierkram-mcp-server"],
      "env": {
        "PAPIERKRAM_API_KEY": "your-api-key",
        "PAPIERKRAM_SUBDOMAIN": "your-subdomain"
      }
    }
  }
}

¿Instalado desde el código fuente? Usa "command": "node" con "args": ["/absolute/path/to/papierkram-mcp-server/dist/index.js"].

Claude Code (CLI)

Añade a tu ~/.claude.json:

{
  "mcpServers": {
    "papierkram": {
      "command": "npx",
      "args": ["-y", "papierkram-mcp-server"],
      "env": {
        "PAPIERKRAM_API_KEY": "your-api-key",
        "PAPIERKRAM_SUBDOMAIN": "your-subdomain"
      }
    }
  }
}

Cursor

Añade a la configuración de MCP de Cursor la misma configuración que en Claude Desktop.

HTTP/SSE (para n8n o clientes personalizados)

# Development
npm run dev:http

# Production
npm run start:http

# Docker
docker compose up -d

Conecta tu cliente MCP a http://localhost:3001/sse.

Desarrollo

npm run dev        # stdio mode with hot reload
npm run dev:http   # HTTP/SSE mode with hot reload
npm run build      # compile TypeScript to dist/

Estructura del Proyecto

src/
├── index.ts              # Stdio entry point
├── server/
│   ├── server.ts         # MCP server setup + tool registration
│   └── http-server.ts    # HTTP/SSE entry point
├── core/tools/           # Tool definitions (one file per API area) + shared helpers
├── api/
│   ├── client.ts         # HTTP client with auth, timeout & error handling
│   ├── errors.ts         # API/network errors -> actionable UserError messages
│   └── format.ts         # Tool-output size guard (truncation)
└── config/
    └── index.ts          # Environment configuration

Contribuciones

¡Las contribuciones son bienvenidas! Por favor, abre un issue o una pull request.

Licencia

MIT - Wagner-Emden IT Services