Overview
What is mcp-server-bigboost?
mcp-server-bigboost is an MCP (Model Context Protocol) server for integration with the Bigboost API by Bigdatacorp. It allows large language models like Claude to query data about individuals (CPF, phone, email) and companies (CNPJ) through standardized search parameters. It is intended for developers building AI assistants that need access to Brazilian public data.
How to use mcp-server-bigboost?
Clone the repository, install dependencies (npm install), copy .env.example to .env and set BIGBOOST_ACCESS_TOKEN and BIGBOOST_TOKEN_ID. Start the server in stdio mode with npm start. For integration with Windsurf, add the server to ~/.codeium/windsurf/mcp_config.json using npx -y mcp-server-bigboost and the required environment variables.
Key features of mcp-server-bigboost
- Query an individual by CPF, phone, or email
- Query a company by CNPJ
- Retrieve QSA (corporate structure) data
- Retrieve full company registration including addresses and contacts
- Rate limiting: 5000 requests per 5 minutes per IP
- 30‑second timeout per request
- Error handling with status codes for various failure categories
Use cases of mcp-server-bigboost
- An AI assistant looks up a person’s basic data using their CPF
- A chatbot verifies a company’s registration details and corporate structure
- A compliance tool checks an individual’s information from a phone number or email
- An application enriches client profiles with official Brazilian public data
FAQ from mcp-server-bigboost
What are the prerequisites to run the server?
Node.js 18 or higher, npm or yarn, and valid Bigboost API credentials (AccessToken and TokenId).
How do I integrate the server with Windsurf?
Add the server to ~/.codeium/windsurf/mcp_config.json with npx -y mcp-server-bigboost as the command and your credentials in the env field, then restart Windsurf.
What are the API rate and timeout limits?
The server enforces a limit of 5000 requests every 5 minutes per IP, each request must complete within 30 seconds.
How can I fix common SDK dependency errors?
Use Node.js 18.x, then reinstall the SDK: npm uninstall @modelcontextprotocol/sdk && npm install @modelcontextprotocol/[email protected]. Clearing npm cache and reinstalling dependencies may also help.
How does the server handle API errors?
Status codes are returned in the response field status. Codes -100 to -999 relate to input data, -1000 to -1199 to login issues, -1200 to -1999 to internal API/dataset problems, and further ranges cover on-demand queries and monitoring.
