gleif-mcp-server

GLEIF MCP Server

Verify any company's legal identity in one question. Look up LEI codes, validate counterparties, and trace corporate ownership structures using the official GLEIF database. Covers 2.8M+ entities across 200+ jurisdictions.

 !lint  

12 tools for LEI lookup, entity search, BIC/SWIFT cross-referencing, corporate ownership, and batch validation. Works with Claude Desktop, Claude Code, Cursor, VS Code, Windsurf, and other MCP-compatible tools.

Use Cases

• KYC & Onboarding: Verify counterparty identities before signing contracts
• Compliance Checks: Validate LEIs for MiFID II, EMIR, or DORA reporting
• Due Diligence: Research corporate ownership chains and ultimate parents
• Financial Analysis: Cross-reference securities (ISIN) and banks (BIC/SWIFT) with their legal entities
• Data Enrichment: Batch-process company lists to add LEI data

What is LEI?

The Legal Entity Identifier (LEI) is a 20-character alphanumeric code that uniquely identifies legal entities participating in financial transactions worldwide. It's mandated by 200+ regulations including MiFID II, EMIR, Dodd-Frank, and DORA.

LEI Format (ISO 17442):

• Characters 1-4: LOU (Local Operating Unit) prefix
• Characters 5-18: Entity-specific identifier
• Characters 19-20: Check digits (mod 97 validation)

Example: HWUPKR0MPOU8FGXBT394 (Apple Inc.)

Features

Core Capabilities

• LEI Lookup: Get full entity details by LEI code
• Batch Lookup: Look up multiple LEIs in a single request (up to 100)
• Entity Search: Find companies by name with fuzzy matching and pagination
• LEI Validation: Verify format, check digits (ISO 17442), and registration status

Financial Identifiers

• BIC/SWIFT Lookup: Find bank LEIs from BIC codes
• ISIN Lookup: Find security issuer LEIs from ISIN codes
• Country Browse: List entities by jurisdiction

Relationships & Compliance

• Corporate Ownership: Parent companies, subsidiaries, ultimate parents
• Fund Relationships: Fund managers, umbrella funds, sub-funds
• Reporting Exceptions: Level 2 data exceptions with reasons
• LEI Issuers: List and details of all Local Operating Units (LOUs)

Performance & Reliability

• Fast Responses: Results are cached locally, so repeat queries return instantly
• No API Key Needed: Works out of the box with GLEIF's public API
• Handles Errors Gracefully: Automatic retries on timeouts or temporary failures
• Stays Within Limits: Built-in rate limiting prevents hitting GLEIF's quotas

Installation

Download Binary

Pre-built binaries for all platforms on the releases page:

| Platform | Binary | |----------|--------| | macOS (Apple Silicon) | gleif-mcp-server-darwin-arm64 | | macOS (Intel) | gleif-mcp-server-darwin-amd64 | | Linux (x64) | gleif-mcp-server-linux-amd64 | | Linux (ARM64) | gleif-mcp-server-linux-arm64 | | Windows (x64) | gleif-mcp-server-windows-amd64.exe |

# macOS/Linux - download and make executable
chmod +x gleif-mcp-server-darwin-arm64

Build from Source

Requires Go 1.25+:

git clone https://github.com/olgasafonova/gleif-mcp-server.git
cd gleif-mcp-server
go build -o gleif-mcp-server .

Install via Go

go install github.com/olgasafonova/gleif-mcp-server@latest

AI Agent Setup

Quickest start: Using Claude Desktop? Just add the config below and restart. Using an IDE like Cursor? Same idea, different config file. Pick your tool below.

Claude Desktop

Step 1: Download the binary

Go to the releases page and download the binary for your system:

• Mac (Apple Silicon M1/M2/M3/M4): gleif-mcp-server-darwin-arm64
• Mac (Intel): gleif-mcp-server-darwin-amd64
• Windows: gleif-mcp-server-windows-amd64.exe

Step 2: Mac only - allow the file to run

macOS blocks downloaded files. Open Terminal and run:

chmod +x ~/Downloads/gleif-mcp-server-darwin-arm64
xattr -d com.apple.quarantine ~/Downloads/gleif-mcp-server-darwin-arm64

Step 3: Open the config file

Mac: Open Finder, press Cmd + Shift + G, paste this path: `` ~/Library/Application Support/Claude/ ``

Windows: Press Win + R, paste this path: `` %APPDATA%\Claude ``

Open claude_desktop_config.json. If it doesn't exist, create it.

Step 4: Add the config

Mac (replace YOUR_USERNAME with your actual username): ``json { "mcpServers": { "gleif": { "command": "/Users/YOUR_USERNAME/Downloads/gleif-mcp-server-darwin-arm64" } } } ``

Windows (replace YOUR_USERNAME - note the double backslashes): ``json { "mcpServers": { "gleif": { "command": "C:\\Users\\YOUR_USERNAME\\Downloads\\gleif-mcp-server-windows-amd64.exe" } } } ``

To find your username: Mac - open Terminal and type whoami. Windows - look at C:\Users\.

Step 5: Restart Claude Desktop

Quit completely (Cmd + Q on Mac) and reopen.

Step 6: Test it

Type in Claude Desktop: `` Look up Apple's LEI using GLEIF ``

You should see Claude call the GLEIF tool and return company data.

Claude Code (CLI)

# Add the server
claude mcp add gleif /path/to/gleif-mcp-server

# Or with scope for all projects
claude mcp add --scope user gleif /path/to/gleif-mcp-server

Cursor IDE

Add to .cursor/mcp.json in your project or ~/.cursor/mcp.json for global config:

{
  "mcpServers": {
    "gleif": {
      "command": "/path/to/gleif-mcp-server"
    }
  }
}

VS Code with Continue Extension

Add to .continue/config.json:

{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "name": "gleif",
        "transport": {
          "type": "stdio",
          "command": "/path/to/gleif-mcp-server"
        }
      }
    ]
  }
}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "gleif": {
      "command": "/path/to/gleif-mcp-server"
    }
  }
}

Cline (VS Code Extension)

Add via Cline's MCP settings or in .vscode/cline_mcp_settings.json:

{
  "mcpServers": {
    "gleif": {
      "command": "/path/to/gleif-mcp-server",
      "args": []
    }
  }
}

Antigravity

Add to ~/.antigravity/mcp.json:

{
  "mcpServers": {
    "gleif": {
      "command": "/path/to/gleif-mcp-server"
    }
  }
}

Not working? Tell us what made it hard — even one sentence helps.

Tools Reference

Core Lookup Tools

| Tool | Description | Parameters | |------|-------------|------------| | lei_lookup | Get full details for a specific LEI | lei (required): 20-char LEI code | | validate_lei | Check format, check digits, and status | lei (required): LEI to validate | | batch_lei_lookup | Look up multiple LEIs at once | leis (required): Comma-separated LEIs (max 100) |

Search Tools

| Tool | Description | Parameters | |------|-------------|------------| | search_entity | Search by company name | query (required), limit (default 20), page (default 1), fuzzy (default true) | | search_by_bic | Find LEI from BIC/SWIFT | bic (required): 8 or 11 char code | | search_by_isin | Find issuer LEI from ISIN | isin (required): 12-char ISIN | | search_by_country | List entities by country | country (required): ISO 2-letter code, limit (default 20) | | autocomplete | Entity name suggestions | prefix (required): min 2 chars, limit (default 10) |

Relationship Tools

| Tool | Description | Parameters | |------|-------------|------------| | get_relationships | Get corporate/fund relationships | lei (required), type: direct-parent, ultimate-parent, children, fund-manager, umbrella-fund, sub-funds |

LEI Issuer Tools

| Tool | Description | Parameters | |------|-------------|------------| | get_lei_issuer | Get details about an LOU | issuer_id (required): LOU identifier | | list_lei_issuers | List all LOUs worldwide | None |

Compliance Tools

| Tool | Description | Parameters | |------|-------------|------------| | get_reporting_exceptions | Get Level 2 reporting exceptions | lei (required): LEI to check |

Usage Examples

Basic LEI Lookup

Prompt: "Look up LEI HWUPKR0MPOU8FGXBT394"

Returns: Full entity details for Apple Inc. including legal name, headquarters address, jurisdiction (US-CA), entity status, registration status, managing LOU, and next renewal date.

Company Search with Pagination

Prompt: "Search for Deutsche Bank, show page 2"

Tool call: ``json { "name": "search_entity", "arguments": { "query": "Deutsche Bank", "limit": 20, "page": 2, "fuzzy": true } } ``

Returns: List of matching entities with pagination info (total results, current page, has more).

Batch LEI Lookup

Prompt: "Look up these LEIs: HWUPKR0MPOU8FGXBT394, 5493006MHB84DD0ZWV18, 549300GKFG0RYRRQ1414"

Returns: Summary of all three entities with LEI, legal name, country, city, and status.

Find Bank by BIC

Prompt: "Find the LEI for BIC DEUTDEFF"

Returns: Deutsche Bank AG's LEI record with full details.

Find Security Issuer

Prompt: "Who issued ISIN US0378331005?"

Returns: Apple Inc. (the issuer of AAPL stock).

Corporate Structure

Prompt: "Who is the ultimate parent of this subsidiary?"

Tool call: ``json { "name": "get_relationships", "arguments": { "lei": "549300GKFG0RYRRQ1414", "type": "ultimate-parent" } } ``

LEI Validation

Prompt: "Is LEI HWUPKR0MPOU8FGXBT394 valid?"

Returns: ``json { "lei": "HWUPKR0MPOU8FGXBT394", "valid": true, "status": "ISSUED", "entityStatus": "ACTIVE", "nextRenewal": "2025-08-15" } ``

Check Reporting Exceptions

Prompt: "Why is parent info missing for this company?"

Tool call: ``json { "name": "get_reporting_exceptions", "arguments": { "lei": "5493006MHB84DD0ZWV18" } } ``

Returns: Exception categories and reasons (e.g., NON_CONSOLIDATING, NATURAL_PERSONS).

List All LEI Issuers

Prompt: "Show me all LEI issuers"

Returns: Complete list of LOUs (Local Operating Units) with name, country, status, and number of sponsored LEIs.

Response Format

All tools return JSON with relevant fields. Example entity record:

{
  "lei": "HWUPKR0MPOU8FGXBT394",
  "legalName": "Apple Inc.",
  "country": "US",
  "city": "Cupertino",
  "status": "ACTIVE",
  "regStatus": "ISSUED"
}

Search results include pagination:

{
  "count": 20,
  "results": [...],
  "pagination": {
    "currentPage": 1,
    "perPage": 20,
    "total": 156,
    "lastPage": 8
  },
  "hasMore": true
}

Error Handling

The server returns structured errors:

| Error Code | Description | Retryable | |------------|-------------|-----------| | not_found | LEI/entity not in GLEIF database | No | | invalid_format | Invalid LEI/BIC/ISIN format | No | | rate_limited | GLEIF API rate limit exceeded | Yes | | timeout | Request timed out | Yes | | server_error | GLEIF API error | Depends on status | | network_error | Connection failed | Yes |

Example error response: ``json { "code": "not_found", "message": "LEI not found in GLEIF database", "statusCode": 404, "retryable": false } ``

Architecture

gleif-mcp-server/
├── main.go                 # Entry point, MCP server setup
├── internal/gleif/
│   ├── client.go          # GLEIF API client with caching & rate limiting
│   ├── client_test.go     # Client and validation tests
│   ├── cache.go           # LRU cache with TTL
│   ├── types.go           # Data structures for API responses
│   └── errors.go          # Structured error types
└── tools/
    ├── definitions.go     # Tool metadata and parameter specs
    ├── handlers.go        # MCP tool implementations
    └── handlers_test.go   # Handler tests with mock server

Technical Details

For developers who want the specifics:

| Setting | Value | |---------|-------| | Cache duration | 15 minutes | | Cache capacity | 1000 entities, 500 searches | | Rate limit | 50 req/min (GLEIF allows 60) | | Retry strategy | 3 attempts with exponential backoff | | Connection pool | 100 max idle, 10 per host |

API Reference

This server wraps the public GLEIF API:

• Base URL: https://api.gleif.org/api/v1
• Authentication: None required
• Rate Limit: 60 requests/minute
• Documentation: https://www.gleif.org/en/lei-data/gleif-api

Troubleshooting

Server won't start

• Check the binary has execute permissions: chmod +x gleif-mcp-server
• Verify the path in your MCP config is absolute, not relative

"Rate limit exceeded" errors

• The server automatically handles rate limiting with retries
• If persistent, reduce concurrent requests or wait a few minutes

"LEI not found" for valid LEI

• The GLEIF database updates daily; recently issued LEIs may not appear immediately
• Verify the LEI format (exactly 20 alphanumeric characters)

Slow responses

• First requests may be slower (cache warming)
• GLEIF API occasionally has latency spikes; retries handle this automatically

Claude Desktop doesn't show the server

• Restart Claude Desktop after editing config
• Check JSON syntax in config file
• Verify the binary path exists and is executable

Development

# Run tests
go test ./...

# Run tests with coverage
go test -coverprofile=coverage.out ./...
go tool cover -html=coverage.out

# Run tests with race detector
go test -race ./...

# Build
go build -o gleif-mcp-server .

Contributing

Contributions welcome. Please open an issue first to discuss proposed changes.

License

MIT License - see LICENSE for details.

More MCP Servers

Check out my other MCP servers:

| Server | Description | Stars | |--------|-------------|-------| | mediawiki-mcp-server | Connect AI to any MediaWiki wiki. Search, read, edit wiki content. | !GitHub stars | | miro-mcp-server | Control Miro whiteboards with AI. Boards, diagrams, mindmaps, and more. | !GitHub stars | | nordic-registry-mcp-server | Access Nordic business registries. Look up companies across Norway, Denmark, Finland, Sweden. | !GitHub stars | | productplan-mcp-server | Talk to your ProductPlan roadmaps. Query OKRs, ideas, launches. | !GitHub stars | | tilbudstrolden-mcp | Nordic grocery deal hunting. Find offers, plan meals, track spending. | !GitHub stars |

---

Acknowledgments

• GLEIF for the public LEI API
• Model Context Protocol for the MCP specification