mcp-nuvem-fiscal — MCP-сервер для Claude Code
MCP-сервер, который даёт агенту доступ к Nuvem Fiscal: выпуск NF-e, NFS-e, NFC-e, CT-e и MDF-e, а также справки по CNPJ и CEP.
claude mcp add mcp-nuvem-fiscal -e NUVEM_FISCAL_CLIENT_SECRET=<NUVEM_FISCAL_CLIENT_SECRET> -- npx -y @codespar/mcp-nuvem-fiscalЧто делает mcp-nuvem-fiscal
Сервер подключается к Nuvem Fiscal по OAuth2 client credentials и сам обновляет токен. Агенту доступны 24 инструмента: create_nfe, get_nfe, cancel_nfe, create_nfse, get_nfse, cancel_nfse, create_nfce, cancel_nfce, create_cte, get_cte, cancel_cte, create_mdfe, get_mdfe, cancel_mdfe, close_mdfe, consult_cnpj, consult_cep, register_company, list_empresas, upload_certificate, get_nfe_events, get_nfe_batch, send_correction_letter_nfe и send_correction_letter_cte. Через них можно выпустить документ, отменить его, отправить письмо-корректировку или подгрузить сертификат A1 в формате .pfx в base64.
Для работы нужны NUVEM_FISCAL_CLIENT_ID и NUVEM_FISCAL_CLIENT_SECRET — без них сервер не авторизуется. Учётные данные выдают в Nuvem Fiscal Developer Portal после регистрации приложения. Есть режим MCP_DEMO=true (или флаг --demo): сервер не обращается к API и отдаёт фикстуры, это удобно для офлайн-прогонов и дымовых тестов интеграции.
Nuvem Fiscal поддерживает среду гомологации (ambiente=2) — документы можно выпускать для проверки, не затрагивая реальный налоговый контур. Пакет распространяется под лицензией MIT.
Какие задачи решает
- выпустить NF-e по данным заказа
- отменить уже выпущенную NFS-e
- получить адрес по CEP для карточки клиента
- проверить компанию по номеру CNPJ
- загрузить сертификат A1 для компании в аккаунте
Примеры запросов агенту
- Выпусти NF-e по этому заказу и верни ID документа
- Найди адрес по CEP 01310-100
- Отмени NFS-e с этим ID и покажи статус
Как установить mcp-nuvem-fiscal
Командой платформы
claude mcp add mcp-nuvem-fiscal -e NUVEM_FISCAL_CLIENT_SECRET=<NUVEM_FISCAL_CLIENT_SECRET> -- npx -y @codespar/mcp-nuvem-fiscalВместо <…> подставьте свои значения
Командой платформы
codex mcp add nuvem-fiscal --env NUVEM_FISCAL_CLIENT_SECRET=<NUVEM_FISCAL_CLIENT_SECRET> -- npx -y @codespar/mcp-nuvem-fiscalВместо <…> подставьте свои значения
Файл настроек
{
"mcpServers": {
"nuvem-fiscal": {
"command": "npx",
"args": [
"-y",
"@codespar/mcp-nuvem-fiscal"
],
"env": {
"NUVEM_FISCAL_CLIENT_SECRET": "<NUVEM_FISCAL_CLIENT_SECRET>"
}
}
}
}Вместо <…> подставьте свои значения
Файл настроек
{
"servers": {
"nuvem-fiscal": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@codespar/mcp-nuvem-fiscal"
],
"env": {
"NUVEM_FISCAL_CLIENT_SECRET": "<NUVEM_FISCAL_CLIENT_SECRET>"
}
}
}
}Вместо <…> подставьте свои значения
Командой платформы
gemini mcp add -e NUVEM_FISCAL_CLIENT_SECRET=<NUVEM_FISCAL_CLIENT_SECRET> nuvem-fiscal npx -y @codespar/mcp-nuvem-fiscalВместо <…> подставьте свои значения
По шагам, с командами для каждой платформы: Как подключить MCP-сервер: Claude Code, Codex, Cursor, VS Code, Gemini CLI и другие
Вопросы о mcp-nuvem-fiscal
Как установить mcp-nuvem-fiscal в Claude Code?
Выполните claude mcp add mcp-nuvem-fiscal -e NUVEM_FISCAL_CLIENT_SECRET=<NUVEM_FISCAL_CLIENT_SECRET> -- npx -y @codespar/mcp-nuvem-fiscal. Второй вариант — claude mcp add --env NUVEM_FISCAL_CLIENT_SECRET=<NUVEM_FISCAL_CLIENT_SECRET> --transport stdio nuvem-fiscal -- npx -y @codespar/mcp-nuvem-fiscal.
Что делает mcp-nuvem-fiscal?
Даёт агенту инструменты Nuvem Fiscal для выпуска и отмены фискальных документов NF-e, NFS-e, NFC-e, CT-e и MDF-e, а также для справок по CNPJ и CEP.
Можно ли протестировать сервер без обращения к API?
Да, при MCP_DEMO=true или с флагом --demo сервер работает на фикстурах. В этом режиме create_nfse выдаёт разные fixture ID на каждый вызов и возвращает переданные servico.codigo, valor и servico.descricao.
