MCP Deps Server

Model Context Protocol server for deps.com.br Smart PJ 005 product integration built with Node.js.

Overview

This MCP server provides access to deps.com.br Smart PJ 005 consultation via DepsMix API v2, enabling AI assistants to perform comprehensive business intelligence and credit analysis operations for companies (CNPJ).

The server handles authentication automatically and implements the correct cache-first consultation flow as specified in the Deps documentation.

Features

• Smart PJ 005 consultation with automatic cache management
• Cache-first approach: First checks for existing consultation data, then performs new consultation if needed
• CNPJ validation: Validates CNPJ mathematical integrity before API calls (PJ only)
• Automatic authentication: Handles login and token refresh transparently
• Comprehensive error handling: Clear messages for common issues

Smart PJ 005 Product Details

Smart PJ 005 provides comprehensive business analysis including:

• Ações judiciais (Legal actions)
• Cadastro pessoa jurídica (Business registration)
• Cheques devolvidos (Returned checks)
• Comportamental resumido (Behavioral summary)
• Consultas detalhadas (Detailed consultations)
• Contatos (Contacts)
• Diagnóstico da análise (Analysis diagnostics)
• Faturamento presumido (Presumed billing)
• Pendências financeiras (Financial pendencies)
• Protestos (Protests)
• Quadro societário (Corporate structure)
• Receita (Revenue)
• Relação empresa participação sócio - Nível 2 de cobertura (Company-partner relations - Level 2)
• Score

Installation

Via NPM (Global - Recomendado)

npm install -g mcp-deps-server

Via NPX (Uso único)

npx mcp-deps-server

Instalação Local

git clone https://github.com/rezultz/mcp-deps
cd mcp-deps
npm install

Configuration

Para instalação via NPM/NPX

Add to your Claude Desktop configuration:

{
  "mcpServers": {
    "deps": {
      "command": "npx",
      "args": ["mcp-deps-server"],
      "env": {
        "DEPS_EMAIL": "[email protected]",
        "DEPS_PASSWORD": "your_password_here"
      }
    }
  }
}

Para instalação local

Add to your Claude Desktop configuration:

{
  "mcpServers": {
    "deps": {
      "command": "/opt/homebrew/bin/node",
      "args": ["index.js"],
      "cwd": "/path/to/mcp-deps",
      "env": {
        "DEPS_EMAIL": "[email protected]",
        "DEPS_PASSWORD": "your_password_here"
      }
    }
  }
}

Alternative Node.js Paths

If your Node.js is installed elsewhere, use the appropriate path:

• System Node.js: /usr/bin/node
• NVM: /Users/username/.nvm/versions/node/vX.X.X/bin/node
• Homebrew (Intel): /usr/local/bin/node
• Homebrew (Apple Silicon): /opt/homebrew/bin/node

Environment Variables

• DEPS_EMAIL: Your deps.com.br account email
• DEPS_PASSWORD: Your deps.com.br account password

Authentication

The server automatically handles authentication with the deps.com.br API v2:

1. Uses your email/password to login via /api/v2/conta/entrar
2. Obtains an access token from the response
3. Includes the Bearer token in all subsequent API requests
4. Re-authenticates automatically when the token expires

No manual token management is required.

Available Tools

deps_consultation

• Purpose: Smart PJ 005 consultation with automatic cache management
• Endpoint: GET /api/v2/consultas/depsmix
• Product: Smart PJ 005 (ID: 059D4CF4)
• Input:
  • document (CNPJ) - required, must be 14-digit CNPJ
• Use case: Complete business intelligence and risk assessment for companies
• Flow:
  1. First attempts consultation with reutilizarDadosExistentes: true (check cache)
  2. If no cached data (success: false), performs new consultation with reutilizarDadosExistentes: false
  3. Returns comprehensive business analysis data
• Status: ✅ Fully functional

Product Configuration

This server is configured to use Smart PJ 005 exclusively:

• Product: Smart PJ 005
• Identifier: 059D4CF4
• Type: Pessoa Jurídica (Business/Company)
• Input: CNPJ only (14 digits)
• Coverage: Level 2 company-partner relations and comprehensive business data

Usage Example

// Simple CNPJ consultation
{
  "document": "11543248000115"
}

// With formatted CNPJ (automatically cleaned)
{
  "document": "11.543.248/0001-15"
}

Common API Responses

• Success: Data returned in value field with success: true
• Cache miss: success: false - triggers new consultation automatically
• No data: "O documento consultado não possui informações na base de dados"
• Invalid CNPJ: Mathematical validation error before API call
• Wrong format: "Smart PJ 005 requires a CNPJ (14 digits)"

Implementation Status

• ✅ Authentication: Working perfectly with API v2
• ✅ API connectivity: Confirmed and functional
• ✅ Document validation: Mathematical CNPJ/CPF validation implemented
• ✅ Cache logic: Fully implemented and working
• ✅ Product identifiers: RESOLVED - All correct identifiers mapped
• ✅ Error handling: Comprehensive error messages for all scenarios

Status: FULLY FUNCTIONAL 🎉

Development

npm install
npm start

Testing

Test the server locally:

export DEPS_EMAIL="[email protected]"
export DEPS_PASSWORD="your_password_here"
node index.js

The server will start and listen for MCP requests via stdin/stdout.