Papierkram

Papierkram MCP Server

Um servidor MCP (Model Context Protocol) para a API de contabilidade do Papierkram.de. Permite que assistentes de IA gerenciem faturas, despesas, contatos, projetos, controle de horas e muito mais diretamente na sua conta Papierkram.

Recursos

• 56 ferramentas cobrindo toda a API v1 do Papierkram
• Instalação via npm: execute diretamente com npx papierkram-mcp-server — sem necessidade de clonar
• Dois transportes: stdio (para Claude Desktop, Cursor, Claude Code) e HTTP/SSE (para n8n, integrações personalizadas)
• Pronto para Docker para fácil implantação auto-hospedada
• TypeScript com validação de esquema Zod em todos os parâmetros

Visão Geral das Ferramentas

Área	Operações	Contagem
Contatos	Empresas e pessoas de contato: listar, obter, criar, atualizar, excluir	10
Faturas	listar, obter, criar, atualizar, excluir, cancelar, arquivar, enviar, baixar PDF	9
Orçamentos	listar, obter, criar, atualizar, excluir, enviar, baixar PDF	7
Despesas	listar, obter, criar, atualizar, excluir	5
Projetos	listar, obter, criar, atualizar, excluir, arquivar, desarquivar	7
Controle de Horas	listar, obter, criar, atualizar, excluir	5
Tarefas	listar, obter, criar, atualizar, excluir	5
Banco	listar, obter conexões bancárias e transações (somente leitura)	4
Conta	Informações da conta, condições de pagamento, propostas	4

Início Rápido

Pré-requisitos

• Node.js 20+ (ou Docker)
• Uma conta Papierkram.de com acesso à API

Obtenha sua Chave de API

Vá em Papierkram > Einstellungen > API e crie uma chave de API.

Opção A: npm (recomendado)

Sem necessidade de clonar — execute diretamente com npx:

npx papierkram-mcp-server

Ou instale globalmente:

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

O servidor usa stdio por padrão; defina PAPIERKRAM_API_KEY e PAPIERKRAM_SUBDOMAIN no seu ambiente ou na configuração do seu cliente MCP (veja Uso).

Opção B: Docker (HTTP/SSE auto-hospedado)

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

O servidor HTTP/SSE estará disponível em http://localhost:3001/sse.

Opção C: Node.js a partir do código-fonte

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

Configuração

Crie um arquivo .env (ou copie de .env.example):

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

Seu subdomínio é a parte antes de .papierkram.de na sua URL do Papierkram.

Uso

Claude Desktop

Adicione ao seu claude_desktop_config.json:

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

Instalou a partir do código-fonte? Use "command": "node" com "args": ["/absolute/path/to/papierkram-mcp-server/dist/index.js"].

Claude Code (CLI)

Adicione ao seu ~/.claude.json:

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

Cursor

Adicione às configurações do seu Cursor MCP com a mesma configuração do Claude Desktop.

HTTP/SSE (para n8n ou clientes personalizados)

# Development
npm run dev:http

# Production
npm run start:http

# Docker
docker compose up -d

Conecte seu cliente MCP a http://localhost:3001/sse.

Desenvolvimento

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/

Estrutura do Projeto

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

Contribuindo

Contribuições são bem-vindas! Abra uma issue ou pull request.

Licença

MIT - Wagner-Emden IT Services