# GLEIF MCP Server
[](https://github.com/GenAICPA/gleif-mcp-server/actions/workflows/ci.yml)
[](https://badge.fury.io/py/gleif-mcp-server)
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/Apache-2.0)
[](https://github.com/psf/black)
A Model Context Protocol (MCP) server that provides seamless access to the GLEIF (Global Legal Entity Identifier Foundation) REST API. This server enables AI assistants and other MCP-compatible applications to query legal entity information, including LEI records, issuer details, and hierarchical relationships between organizations.
## Features
### 🔍 **LEI Record Management**
- **Search & Retrieve**: Find LEI records by various criteria (legal name, LEI code, jurisdiction)
- **Fuzzy Matching**: Approximate search with auto-completion for entity discovery
- **Live Data**: Real-time access to the most current GLEIF database
### 🏢 **Entity Information**
- **Legal Entity Details**: Complete legal name, jurisdiction, status, and registration info
- **Address Data**: Headquarters and legal addresses with full geographical details
- **Entity Relationships**: Parent-subsidiary relationships and ownership structures
### 🌍 **Reference Data**
- **Country Codes**: ISO 3166 country code lookups and validation
- **Legal Forms**: Entity Legal Form (ELF) code reference data
- **Issuer Network**: Information about LEI issuing organizations (LOUs)
### 🔧 **Developer Tools**
- **Field Metadata**: Comprehensive API field documentation and filtering capabilities
- **Pagination**: Efficient handling of large result sets
- **Type Safety**: Full Python type hints and Pydantic validation
## Quick Start
### Installation
```bash
pip install gleif-mcp-server
```
### Start the MCP Server
```bash
# Start server on default port (8000)
gleif-mcp-server
# Or specify custom port
gleif-mcp-server --port 8080
```
### Use as Python Client
```python
from gleif_mcp import client
# Get specific LEI record
lei_data = client.get_lei_record("529900T8BM49AURSDO55")
print(f"Entity: {lei_data['entity']['legalName']}")
# Search for entities
results = client.search_lei_records("entity.legalName", "Citibank")
for record in results['data']:
print(f"Found: {record['entity']['legalName']}")
# Fuzzy search with suggestions
suggestions = client.fuzzy_completions("entity.legalName", "Apple Inc")
```
## MCP Integration
This server is compatible with any MCP client, including:
- **Claude Desktop**: Add to your `claude_desktop_config.json`
- **Cline/Windsurf**: Configure as an MCP server
- **Custom Applications**: Use the standard MCP protocol
### Configuration Example
```json
{
"mcpServers": {
"gleif": {
"command": "gleif-mcp-server",
"args": []
}
}
}
```
## API Coverage
The server provides access to all major GLEIF API endpoints:
| **Category** | **Endpoint** | **Description** |
|--------------|--------------|-----------------|
| **LEI Records** | `/lei-records` | Search and retrieve LEI records |
| **LEI Records** | `/lei-records/{lei}` | Get specific LEI record by code |
| **Search** | `/lei-records/fuzzy-completions` | Fuzzy matching for entity names |
| **Search** | `/lei-records/auto-completions` | Auto-complete suggestions |
| **Issuers** | `/lei-issuers` | List accredited LEI issuers |
| **Issuers** | `/lei-issuers/{id}` | Get specific issuer details |
| **Reference** | `/countries` | ISO 3166 country codes |
| **Reference** | `/entity-legal-forms` | ELF codes and descriptions |
| **Metadata** | `/fields` | API field catalog and filtering options |
## Development
### Setup Development Environment
```bash
# Clone the repository
git clone https://github.com/GenAICPA/gleif-mcp-server.git
cd gleif-mcp-server
# Install in development mode
pip install -e ".[dev]"
# Install pre-commit hooks
pre-commit install
```
### Run Tests
```bash
# Run all tests
pytest
# Run tests with coverage
pytest --cov=gleif_mcp
# Skip live API tests (for CI)
pytest -m "not live"
# Run only integration tests
pytest -m integration
```
### Code Quality
```bash
# Format code
black gleif_mcp tests
# Lint code
ruff check gleif_mcp tests
# Type checking
mypy gleif_mcp
```
## Examples
### Find Entity by Name
```python
# Search for entities containing "Microsoft"
results = client.search_lei_records("entity.legalName", "*Microsoft*")
for entity in results['data'][:5]: # Show first 5 results
print(f"LEI: {entity['lei']}")
print(f"Name: {entity['entity']['legalName']}")
print(f"Country: {entity['entity']['jurisdiction']}")
print("---")
```
### Get Entity Hierarchy
```python
# Get parent company information
lei = "529900T8BM49AURSDO55" # Example LEI
record = client.get_lei_record(lei)
if record['entity'].get('parent'):
parent_lei = record['entity']['parent']['lei']
parent_data = client.get_lei_record(parent_lei)
print(f"Parent: {parent_data['entity']['legalName']}")
```
### Country and Legal Form Lookup
```python
# Get country information
country = client.get_country("US")
print(f"Country: {country['name']} ({country['code']})")
# List available legal forms
legal_forms = client.list_entity_legal_forms()
for form in legal_forms['data'][:10]:
print(f"{form['code']}: {form['name']}")
```
## Contributing
We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Make your changes and add tests
4. Ensure all tests pass and code is formatted
5. Submit a pull request
## License
This project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.
## Acknowledgments
- [GLEIF](https://www.gleif.org/) for providing the comprehensive LEI database and API
- [Model Context Protocol](https://modelcontextprotocol.io/) for the standard protocol specification
- [FastAPI](https://fastapi.tiangolo.com/) for the excellent web framework
## Support
- 📖 [Documentation](https://github.com/GenAICPA/gleif-mcp-server#readme)
- 🐛 [Report Issues](https://github.com/GenAICPA/gleif-mcp-server/issues)
- 💬 [Discussions](https://github.com/GenAICPA/gleif-mcp-server/discussions)
---
**Note**: This is an unofficial implementation. GLEIF does not endorse or maintain this server.
Raw data
{
"_id": null,
"home_page": null,
"name": "gleif-mcp-server",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "api, gleif, legal-entity-identifier, lei, mcp, server",
"author": null,
"author_email": "GenAICPA <contact@genacpa.com>",
"download_url": "https://files.pythonhosted.org/packages/ee/de/c9f43a08b7f19d95e68742d1c035885d2abe005af7215f17fae891400ec5/gleif_mcp_server-0.1.2.tar.gz",
"platform": null,
"description": "# GLEIF MCP Server\n\n[](https://github.com/GenAICPA/gleif-mcp-server/actions/workflows/ci.yml)\n[](https://badge.fury.io/py/gleif-mcp-server)\n[](https://www.python.org/downloads/)\n[](https://opensource.org/licenses/Apache-2.0)\n[](https://github.com/psf/black)\n\nA Model Context Protocol (MCP) server that provides seamless access to the GLEIF (Global Legal Entity Identifier Foundation) REST API. This server enables AI assistants and other MCP-compatible applications to query legal entity information, including LEI records, issuer details, and hierarchical relationships between organizations.\n\n## Features\n\n### \ud83d\udd0d **LEI Record Management**\n- **Search & Retrieve**: Find LEI records by various criteria (legal name, LEI code, jurisdiction)\n- **Fuzzy Matching**: Approximate search with auto-completion for entity discovery\n- **Live Data**: Real-time access to the most current GLEIF database\n\n### \ud83c\udfe2 **Entity Information** \n- **Legal Entity Details**: Complete legal name, jurisdiction, status, and registration info\n- **Address Data**: Headquarters and legal addresses with full geographical details\n- **Entity Relationships**: Parent-subsidiary relationships and ownership structures\n\n### \ud83c\udf0d **Reference Data**\n- **Country Codes**: ISO 3166 country code lookups and validation \n- **Legal Forms**: Entity Legal Form (ELF) code reference data\n- **Issuer Network**: Information about LEI issuing organizations (LOUs)\n\n### \ud83d\udd27 **Developer Tools**\n- **Field Metadata**: Comprehensive API field documentation and filtering capabilities\n- **Pagination**: Efficient handling of large result sets\n- **Type Safety**: Full Python type hints and Pydantic validation\n\n## Quick Start\n\n### Installation\n\n```bash\npip install gleif-mcp-server\n```\n\n### Start the MCP Server\n\n```bash\n# Start server on default port (8000)\ngleif-mcp-server\n\n# Or specify custom port\ngleif-mcp-server --port 8080\n```\n\n### Use as Python Client\n\n```python\nfrom gleif_mcp import client\n\n# Get specific LEI record\nlei_data = client.get_lei_record(\"529900T8BM49AURSDO55\")\nprint(f\"Entity: {lei_data['entity']['legalName']}\")\n\n# Search for entities\nresults = client.search_lei_records(\"entity.legalName\", \"Citibank\")\nfor record in results['data']:\n print(f\"Found: {record['entity']['legalName']}\")\n\n# Fuzzy search with suggestions\nsuggestions = client.fuzzy_completions(\"entity.legalName\", \"Apple Inc\")\n```\n\n## MCP Integration\n\nThis server is compatible with any MCP client, including:\n\n- **Claude Desktop**: Add to your `claude_desktop_config.json`\n- **Cline/Windsurf**: Configure as an MCP server\n- **Custom Applications**: Use the standard MCP protocol\n\n### Configuration Example\n\n```json\n{\n \"mcpServers\": {\n \"gleif\": {\n \"command\": \"gleif-mcp-server\",\n \"args\": []\n }\n }\n}\n```\n\n## API Coverage\n\nThe server provides access to all major GLEIF API endpoints:\n\n| **Category** | **Endpoint** | **Description** |\n|--------------|--------------|-----------------|\n| **LEI Records** | `/lei-records` | Search and retrieve LEI records |\n| **LEI Records** | `/lei-records/{lei}` | Get specific LEI record by code |\n| **Search** | `/lei-records/fuzzy-completions` | Fuzzy matching for entity names |\n| **Search** | `/lei-records/auto-completions` | Auto-complete suggestions |\n| **Issuers** | `/lei-issuers` | List accredited LEI issuers |\n| **Issuers** | `/lei-issuers/{id}` | Get specific issuer details |\n| **Reference** | `/countries` | ISO 3166 country codes |\n| **Reference** | `/entity-legal-forms` | ELF codes and descriptions |\n| **Metadata** | `/fields` | API field catalog and filtering options |\n\n## Development\n\n### Setup Development Environment\n\n```bash\n# Clone the repository\ngit clone https://github.com/GenAICPA/gleif-mcp-server.git\ncd gleif-mcp-server\n\n# Install in development mode\npip install -e \".[dev]\"\n\n# Install pre-commit hooks\npre-commit install\n```\n\n### Run Tests\n\n```bash\n# Run all tests\npytest\n\n# Run tests with coverage\npytest --cov=gleif_mcp\n\n# Skip live API tests (for CI)\npytest -m \"not live\"\n\n# Run only integration tests\npytest -m integration\n```\n\n### Code Quality\n\n```bash\n# Format code\nblack gleif_mcp tests\n\n# Lint code \nruff check gleif_mcp tests\n\n# Type checking\nmypy gleif_mcp\n```\n\n## Examples\n\n### Find Entity by Name\n\n```python\n# Search for entities containing \"Microsoft\"\nresults = client.search_lei_records(\"entity.legalName\", \"*Microsoft*\")\n\nfor entity in results['data'][:5]: # Show first 5 results\n print(f\"LEI: {entity['lei']}\")\n print(f\"Name: {entity['entity']['legalName']}\")\n print(f\"Country: {entity['entity']['jurisdiction']}\")\n print(\"---\")\n```\n\n### Get Entity Hierarchy\n\n```python\n# Get parent company information\nlei = \"529900T8BM49AURSDO55\" # Example LEI\nrecord = client.get_lei_record(lei)\n\nif record['entity'].get('parent'):\n parent_lei = record['entity']['parent']['lei'] \n parent_data = client.get_lei_record(parent_lei)\n print(f\"Parent: {parent_data['entity']['legalName']}\")\n```\n\n### Country and Legal Form Lookup\n\n```python\n# Get country information\ncountry = client.get_country(\"US\")\nprint(f\"Country: {country['name']} ({country['code']})\")\n\n# List available legal forms\nlegal_forms = client.list_entity_legal_forms()\nfor form in legal_forms['data'][:10]:\n print(f\"{form['code']}: {form['name']}\")\n```\n\n## Contributing\n\nWe welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Make your changes and add tests\n4. Ensure all tests pass and code is formatted\n5. Submit a pull request\n\n## License\n\nThis project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.\n\n## Acknowledgments\n\n- [GLEIF](https://www.gleif.org/) for providing the comprehensive LEI database and API\n- [Model Context Protocol](https://modelcontextprotocol.io/) for the standard protocol specification\n- [FastAPI](https://fastapi.tiangolo.com/) for the excellent web framework\n\n## Support\n\n- \ud83d\udcd6 [Documentation](https://github.com/GenAICPA/gleif-mcp-server#readme)\n- \ud83d\udc1b [Report Issues](https://github.com/GenAICPA/gleif-mcp-server/issues) \n- \ud83d\udcac [Discussions](https://github.com/GenAICPA/gleif-mcp-server/discussions)\n\n---\n\n**Note**: This is an unofficial implementation. GLEIF does not endorse or maintain this server.",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Model Context Protocol (MCP) server for the GLEIF (Global Legal Entity Identifier Foundation) REST API",
"version": "0.1.2",
"project_urls": {
"Documentation": "https://github.com/GenAICPA/gleif-mcp-server#readme",
"Homepage": "https://github.com/GenAICPA/gleif-mcp-server",
"Issues": "https://github.com/GenAICPA/gleif-mcp-server/issues",
"Repository": "https://github.com/GenAICPA/gleif-mcp-server"
},
"split_keywords": [
"api",
" gleif",
" legal-entity-identifier",
" lei",
" mcp",
" server"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "2f52e887813c6b25c14051e540b3621a1b60ebc4f5f1f37a3a9b0139100e0881",
"md5": "7ca98d7ccfab847a23fec4a0f791712e",
"sha256": "a3f4de10cd97ef21d2720008dbe22823c7ae8223588cc565dc289f0ae253d995"
},
"downloads": -1,
"filename": "gleif_mcp_server-0.1.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7ca98d7ccfab847a23fec4a0f791712e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 14894,
"upload_time": "2025-08-15T21:26:12",
"upload_time_iso_8601": "2025-08-15T21:26:12.679644Z",
"url": "https://files.pythonhosted.org/packages/2f/52/e887813c6b25c14051e540b3621a1b60ebc4f5f1f37a3a9b0139100e0881/gleif_mcp_server-0.1.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "eedec9f43a08b7f19d95e68742d1c035885d2abe005af7215f17fae891400ec5",
"md5": "109f44db31fa3decadd47b20b006fa13",
"sha256": "f471393f4d0e439d50d36462712056bfd6f12087c06f7053241e9347243abddb"
},
"downloads": -1,
"filename": "gleif_mcp_server-0.1.2.tar.gz",
"has_sig": false,
"md5_digest": "109f44db31fa3decadd47b20b006fa13",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 26105,
"upload_time": "2025-08-15T21:26:14",
"upload_time_iso_8601": "2025-08-15T21:26:14.259483Z",
"url": "https://files.pythonhosted.org/packages/ee/de/c9f43a08b7f19d95e68742d1c035885d2abe005af7215f17fae891400ec5/gleif_mcp_server-0.1.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-15 21:26:14",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "GenAICPA",
"github_project": "gleif-mcp-server#readme",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "gleif-mcp-server"
}
JSON
