# Brreg MCP Server

A Model Context Protocol (MCP) server for interacting with Brønnøysundregistrene (Brreg) API - Norwegian Business Registry.

## Features

- **Company Search**: Search for companies with various filters
- **Company Details**: Get detailed information about specific companies
- **Company Roles**: Retrieve roles and board members
- **Subunit Search**: Search for business units/subunits
- **Subunit Details**: Get detailed information about specific subunits
- **Organization Forms**: Get organization forms and their descriptions
- **Municipalities**: Get Norwegian municipalities and their details
- **Role Information**: Get role types, role group types, and representatives
- **Updates Tracking**: Get updates for companies and subunits
- **NACE Codes**: Search and filter by NACE industry codes with hierarchical support
- **Error Handling**: Comprehensive error handling with validation
- **Type Safety**: Full TypeScript support with proper type definitions

## Installation

### Option 1: Install from npm (Recommended)

```bash
# Install globally
npm install -g brreg-mcp-server

# Or install locally in your project
npm install brreg-mcp-server
```

### Option 2: Clone from source

```bash
# Clone repository
git clone https://github.com/david/brreg-mcp-server.git
cd brreg-mcp-server

# Install dependencies
npm install

# Build project
npm run build

# Start server
npm start
```

## Development

```bash
# Run in development mode
npm run dev
```

## MCP Tools

### 1. `search_companies`
Search for companies in Norwegian Business Registry.

**Parameters:**
- `name` (string): Company name (free text, 1-180 characters)
- `organizationNumber` (array): Organization numbers (9 digits each)
- `parentCompany` (string): Parent company organization number
- `fromEmployees` (number): Minimum number of employees
- `toEmployees` (number): Maximum number of employees
- `bankrupt` (boolean): Filter by bankruptcy status
- `registeredInVAT` (boolean): Filter by VAT registration
- `registeredInBusinessRegister` (boolean): Filter by business register status
- `organizationForm` (array): Organization forms (e.g., AS, ENK)
- `municipalityNumber` (array): Municipality numbers (4 digits each)
- `industryCode` (array): Industry codes (e.g., 41.109, 01.1)
- `page` (number): Page number (default: 1)
- `size` (number): Page size (default: 20)
- `sort` (string): Sort field and order (e.g., antallAnsatte,ASC)

### 2. `get_company`
Get detailed information about a specific company.

**Parameters:**
- `organizationNumber` (string, required): Organization number (9 digits)

### 3. `get_company_roles`
Get all roles for a specific company.

**Parameters:**
- `organizationNumber` (string, required): Organization number (9 digits)

### 4. `search_subunits`
Search for business units/subunits.

**Parameters:**
- `name` (string): Subunit name
- `organizationNumber` (array): Organization numbers
- `parentCompany` (string): Parent company
- `fromEmployees` (number): Minimum employees
- `toEmployees` (number): Maximum employees
- `registeredInVAT` (boolean): VAT registration status
- `page` (number): Page number
- `size` (number): Page size

### 5. `get_subunit`
Get detailed information about a specific subunit.

**Parameters:**
- `organizationNumber` (string, required): Organization number (9 digits)

### 6. `get_organization_forms`
Get all organization forms.

**Parameters:**
- `page` (number): Page number (default: 1)
- `size` (number): Page size (default: 20)
- `sort` (string): Sort field and order (e.g., kode,ASC)

### 7. `get_organization_forms_for_units`
Get organization forms for main units.

**Parameters:**
- `page` (number): Page number (default: 1)
- `size` (number): Page size (default: 20)
- `sort` (string): Sort field and order (e.g., kode,ASC)

### 8. `get_organization_forms_for_subunits`
Get organization forms for subunits.

**Parameters:**
- `page` (number): Page number (default: 1)
- `size` (number): Page size (default: 20)
- `sort` (string): Sort field and order (e.g., kode,ASC)

### 9. `get_organization_form`
Get specific organization form by code.

**Parameters:**
- `organizationCode` (string, required): Organization form code (e.g., AS, ENK, ASA)

### 10. `get_municipalities`
Get all Norwegian municipalities.

**Parameters:**
- `page` (number): Page number (default: 1)
- `size` (number): Page size (default: 20)
- `sort` (string): Sort field and order (e.g., navn,ASC)

### 11. `get_municipality`
Get specific municipality by municipality number.

**Parameters:**
- `municipalityNumber` (string, required): Municipality number (4 digits)

### 12. `get_role_types`
Get all role types.

### 13. `get_role_group_types`
Get all role group types.

### 14. `get_role_representatives`
Get all role representatives.

### 15. `get_company_updates`
Get updates for companies with optional filters.

**Parameters:**
- `date` (string): Show updates from and including this timestamp (ISO-8601)
- `updatedBefore` (string): Show updates to and including this timestamp (ISO-8601)
- `updateId` (number): Show only updates from and including update ID (>= 1)
- `organizationNumber` (array): Comma-separated list of organization numbers
- `includeChanges` (boolean): Include the changes that caused the update to be published
- `page` (number): Page number (default: 1)
- `size` (number): Page size (default: 20, max: 10000)
- `sort` (string): Sort field and order (e.g., id,ASC). Only id is supported

### 16. `get_subunit_updates`
Get updates for subunits with optional filters.

**Parameters:**
- `date` (string): Show updates from and including this timestamp (ISO-8601)
- `updatedBefore` (string): Show updates to and including this timestamp (ISO-8601)
- `updateId` (number): Show only updates from and including update ID (>= 1)
- `organizationNumber` (array): Comma-separated list of organization numbers
- `includeChanges` (boolean): Include the changes that caused the update to be published
- `page` (number): Page number (default: 1)
- `size` (number): Page size (default: 20, max: 10000)
- `sort` (string): Sort field and order (e.g., id,ASC). Only id is supported

### 17. `search_nace_codes`
Search NACE industry codes with hierarchical filtering support using the full SN2025 classification.

**Parameters:**
- `searchText` (string): Text to search for in NACE code names, short names, codes, or notes
- `parentCode` (string): Get all child codes for a specific NACE parent code (e.g., "01.1" will return all subcategories)
- `exactCode` (string): Get specific NACE code by exact code
- `level` (string): Filter by NACE level (1-5). Level 1 = sections, Level 2 = divisions, Level 3 = groups, Level 4 = classes, Level 5 = national subcategories
- `includeHierarchy` (boolean): Include full hierarchical path in results (default: true)
- `includeNotes` (boolean): Include detailed notes in results (default: false)

### 18. `get_services`
Get all available services from Brreg API.

## Usage Examples

### Search for software companies in Oslo
```json
{
  "name": "search_companies",
  "arguments": {
    "industryCode": ["62"],
    "municipalityNumber": ["0301"],
    "fromEmployees": 10,
    "size": 50
  }
}
```

### Get company details
```json
{
  "name": "get_company",
  "arguments": {
    "organizationNumber": "123456789"
  }
}
```

### Get subunit details
```json
{
  "name": "get_subunit",
  "arguments": {
    "organizationNumber": "987654321"
  }
}
```

### Get organization forms
```json
{
  "name": "get_organization_forms",
  "arguments": {
    "page": 1,
    "size": 50
  }
}
```

### Get specific organization form
```json
{
  "name": "get_organization_form",
  "arguments": {
    "organizationCode": "AS"
  }
}
```

### Get municipalities
```json
{
  "name": "get_municipalities",
  "arguments": {
    "page": 1,
    "size": 20,
    "sort": "navn,ASC"
  }
}
```

### Get company updates
```json
{
  "name": "get_company_updates",
  "arguments": {
    "date": "2024-01-01T00:00:00.000Z",
    "size": 50,
    "includeChanges": true
  }
}
```

### Search NACE codes
```json
{
  "name": "search_nace_codes",
  "arguments": {
    "searchText": "software",
    "level": "4",
    "includeHierarchy": true
  }
}
```

### Get NACE codes by parent
```json
{
  "name": "search_nace_codes",
  "arguments": {
    "parentCode": "62",
    "includeNotes": true
  }
}
```



## Configuration

### Claude Desktop Setup

Add this to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "brreg": {
      "command": "npx",
      "args": ["brreg-mcp-server"]
    }
  }
}
```

Or if installed globally:

```json
{
  "mcpServers": {
    "brreg": {
      "command": "brreg-mcp-server"
    }
  }
}
```

## Error Handling

The server provides comprehensive error handling:

- **Validation Errors**: Invalid input parameters
- **Not Found Errors**: Company or resource not found
- **Rate Limit Errors**: API rate limits exceeded
- **Server Errors**: Temporary server issues
- **Network Errors**: Connection problems

## Data Types

The server provides proper TypeScript types for:

- Company information
- Subunit data
- Role information
- API responses
- Error responses

## License

MIT License

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

## Support

For issues related to the Brreg API itself, visit [Brreg's documentation](https://www.brreg.no/en/use-of-data-from-the-bronnoysund-register-centre/datasets-and-api/).

For issues with this MCP server, please create an issue in the repository.