`pe_ruc_search`

Pack: peru-sunat-ruc · Connect: https://pipeworx.io/mcp (see Connect below for a single-pack URL)

No MCP client? Call it directly: GET https://gateway.pipeworx.io/v1/tools/pe_ruc_search for the schema, then POST the same URL with its arguments for the data.

Search Peruvian companies by name in the SUNAT register, optionally by ubigeo.

Tool description as the model sees it

Search SUNAT’s published taxpayer register by company name (razon social) — legal entities only (RUC prefix 20 and government offices); natural persons are excluded entirely and are never returned. Accent-insensitive substring match: every word of 3+ letters must appear in the name. Active registrations are listed before deregistered ones. Optionally restrict to a place with a ubigeo prefix (2 digits = department, e.g. “15” Lima; 4 = province; 6 = district). Returns RUC, name, status and address so you can pick the right one.

Parameters

Name	Type	Required	Description
`name`	string	yes	Company name or part of it, e.g. “BANCO DE CREDITO” or “alicorp”.
`ubigeo`	string	no	Optional ubigeo prefix: 2, 4 or 6 digits (e.g. “15” Lima department, “150122” Miraflores).
`active_only`	boolean	no	If true, return only registrations whose status is ACTIVO (default false: active first, then the rest).
`limit`	number	no	Maximum results (1-50, default 10).

Example call

Arguments

{
  "name": "alicorp",
  "ubigeo": "15",
  "limit": 3
}

curl

curl -X POST https://gateway.pipeworx.io/peru-sunat-ruc/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"pe_ruc_search","arguments":{"name":"alicorp","ubigeo":"15","limit":3}}}'

TypeScript (@pipeworx/sdk)

import { Pipeworx } from '@pipeworx/sdk';
const pipeworx = new Pipeworx();

const result = await pipeworx.call('pe_ruc_search', {
  "name": "alicorp",
  "ubigeo": "15",
  "limit": 3
});

Response shape

Field	Type	Description
`found`	boolean
`reason`	string
`query`	string
`ubigeo`	string \| null
`returned`	number
`message`	string
`hint`	string
`results`	array
`data_as_of`	string \| null
`source`	string

Full JSON Schema

{
  "type": "object",
  "additionalProperties": true,
  "properties": {
    "found": {
      "type": "boolean"
    },
    "reason": {
      "type": "string"
    },
    "query": {
      "type": "string"
    },
    "ubigeo": {
      "type": [
        "string",
        "null"
      ]
    },
    "returned": {
      "type": "number"
    },
    "message": {
      "type": "string"
    },
    "hint": {
      "type": "string"
    },
    "results": {
      "type": "array",
      "items": {
        "type": "object",
        "additionalProperties": true,
        "properties": {
          "ruc": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "holder_type": {
            "type": "string"
          },
          "holder_type_basis": {
            "type": "string"
          },
          "status": {
            "type": [
              "string",
              "null"
            ]
          },
          "status_gloss": {
            "type": [
              "string",
              "null"
            ]
          },
          "is_active": {
            "type": "boolean"
          },
          "domicile_condition": {
            "type": [
              "string",
              "null"
            ]
          },
          "domicile_condition_gloss": {
            "type": [
              "string",
              "null"
            ]
          },
          "check_digit_valid": {
            "type": "boolean"
          },
          "ubigeo": {
            "type": [
              "string",
              "null"
            ]
          },
          "department_code": {
            "type": [
              "string",
              "null"
            ]
          },
          "department": {
            "type": [
              "string",
              "null"
            ]
          },
          "address": {
            "type": [
              "string",
              "null"
            ]
          },
          "address_parts": {
            "type": "object",
            "additionalProperties": true
          },
          "address_withheld": {
            "type": "string"
          }
        }
      }
    },
    "data_as_of": {
      "type": [
        "string",
        "null"
      ]
    },
    "source": {
      "type": "string"
    }
  }
}

Connect

Add this to your MCP client config — every tool in the catalog, including this one — or use one-click install buttons:

{
  "mcpServers": {
    "pipeworx": {
      "url": "https://pipeworx.io/mcp"
    }
  }
}

Connect to just the peru-sunat-ruc pack

{
  "mcpServers": {
    "peru-sunat-ruc": {
      "url": "https://gateway.pipeworx.io/peru-sunat-ruc/mcp"
    }
  }
}

See Getting Started for client-specific install steps.

pe_ruc_search