{"id":45398147,"url":"https://github.com/NimbleBrainInc/mcp-abstract","last_synced_at":"2026-03-06T20:01:34.287Z","repository":{"id":330325918,"uuid":"1076286826","full_name":"NimbleBrainInc/mcp-abstract","owner":"NimbleBrainInc","description":"MCP server for Abstract API - validate emails, phone numbers, enrich company data, IP geolocation, and currency conversion.","archived":false,"fork":false,"pushed_at":"2026-02-14T02:51:42.000Z","size":45,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-14T09:37:09.533Z","etag":null,"topics":["abstract","mcp","mcpb","nimblebrain","nimbletools"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/NimbleBrainInc.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-14T16:43:25.000Z","updated_at":"2026-02-14T02:51:45.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/NimbleBrainInc/mcp-abstract","commit_stats":null,"previous_names":["nimblebraininc/mcp-abstract"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/NimbleBrainInc/mcp-abstract","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NimbleBrainInc%2Fmcp-abstract","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NimbleBrainInc%2Fmcp-abstract/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NimbleBrainInc%2Fmcp-abstract/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NimbleBrainInc%2Fmcp-abstract/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/NimbleBrainInc","download_url":"https://codeload.github.com/NimbleBrainInc/mcp-abstract/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NimbleBrainInc%2Fmcp-abstract/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30195529,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-06T19:07:06.838Z","status":"ssl_error","status_checked_at":"2026-03-06T18:57:34.882Z","response_time":250,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["abstract","mcp","mcpb","nimblebrain","nimbletools"],"created_at":"2026-02-21T19:44:50.174Z","updated_at":"2026-03-06T20:01:34.280Z","avatar_url":"https://github.com/NimbleBrainInc.png","language":"Python","funding_links":[],"categories":["Utilities"],"sub_categories":[],"readme":"# MCP Server - Abstract\n\n[![NimbleTools Registry](https://img.shields.io/badge/NimbleTools-Registry-green)](https://github.com/nimbletoolsinc/mcp-registry)\n[![NimbleBrain Platform](https://img.shields.io/badge/NimbleBrain-Platform-blue)](https://www.nimblebrain.ai)\n[![Discord](https://img.shields.io/badge/Discord-%235865F2.svg?logo=discord\u0026logoColor=white)](https://www.nimblebrain.ai/discord?utm_source=github\u0026utm_medium=readme\u0026utm_campaign=mcp-abstract\u0026utm_content=discord-badge)\n\n\n[![Python 3.13+](https://img.shields.io/badge/python-3.13+-blue.svg)](https://www.python.org/downloads/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![CI](https://github.com/NimbleBrainInc/mcp-abstract/actions/workflows/ci.yaml/badge.svg)](https://github.com/NimbleBrainInc/mcp-abstract/actions)\n\n\n## About\n\n**MCP Server - Abstract** is a production-ready Model Context Protocol (MCP) server that provides seamless integration with [Abstract's](https://www.abstractapi.com/)'s comprehensive suite of data validation, enrichment, and intelligence services. Built with enterprise-grade architecture, this server enables AI assistants and agents to validate emails and phone numbers, enrich company data, perform IP geolocation, convert currencies, and much more—all through a type-safe, async-first interface.\n\n## Features\n\n- **Full API Coverage**: Complete implementation of 15+ Abstract API endpoints\n- **Strongly Typed**: All responses use Pydantic models for type safety\n- **HTTP Transport**: Supports streamable-http with health endpoint\n- **Async/Await**: Built on aiohttp for high performance\n- **Type Safe**: Full mypy strict mode compliance\n- **Production Ready**: Docker support, comprehensive tests, linting\n- **Developer Friendly**: Makefile commands, auto-formatting, fast feedback\n\n## Supported APIs\n\n### Data Validation\n- **Email Validation** - Verify email deliverability, detect disposable emails\n- **Phone Validation** - Validate phone numbers, identify carriers\n- **VAT Validation** - Validate EU VAT numbers\n\n### IP Intelligence\n- **IP Geolocation** - Get location from IP address\n- **IP Geolocation with Security** - Get location with VPN/proxy/datacenter detection\n- **IP Info** - ISP, ASN, and connection details\n\n### Time \u0026 Location\n- **Timezone** - Get timezone from location or coordinates\n- **Timezone Conversion** - Convert times between timezones\n- **Holidays** - Get public holidays by country/year\n\n### Financial\n- **Exchange Rates** - Live currency exchange rates\n- **Currency Conversion** - Convert amounts between currencies\n\n### Web \u0026 Business\n- **Company Enrichment** - Get company data from domain\n- **Web Scraping** - Extract structured data from websites\n- **Screenshots** - Generate website screenshots\n\n## Installation\n\n### Using uv (recommended)\n\n```bash\n# Install dependencies\nuv pip install -e .\n\n# Install with dev dependencies\nuv pip install -e . --group dev\n```\n\n### Using pip\n\n```bash\npip install -e .\n```\n\n## Configuration\n\n**Important**: Abstract API uses **different API keys for different services**. You need to get a separate key for each service you want to use.\n\n### Setup\n\n1. Get your API keys from [Abstract API Dashboard](https://app.abstractapi.com/api)\n   - Each service (Email, Phone, IP, etc.) has its own API key\n   - You only need keys for the services you plan to use\n\n2. Create a `.env` file in the project root:\n\n```bash\n# Copy the example file\ncp .env.example .env\n\n# Edit .env and add your service-specific keys\n```\n\n3. Add your keys to `.env`:\n\n```bash\n# Example: If you only use IP geolocation and phone validation\nABSTRACT_IP_API_KEY=your_ip_key_here\nABSTRACT_PHONE_API_KEY=your_phone_key_here\n```\n\nAvailable service key names:\n- `ABSTRACT_EMAIL_API_KEY` - Email validation\n- `ABSTRACT_PHONE_API_KEY` - Phone validation\n- `ABSTRACT_VAT_API_KEY` - VAT validation\n- `ABSTRACT_IP_API_KEY` - IP geolocation (also used for VPN detection)\n- `ABSTRACT_TIMEZONE_API_KEY` - Timezone services\n- `ABSTRACT_HOLIDAYS_API_KEY` - Holiday lookup\n- `ABSTRACT_EXCHANGE_API_KEY` - Currency exchange rates\n- `ABSTRACT_COMPANY_API_KEY` - Company enrichment\n- `ABSTRACT_SCRAPE_API_KEY` - Web scraping\n- `ABSTRACT_SCREENSHOT_API_KEY` - Screenshot generation\n\n**Note**: The `.env` file is automatically loaded when the server starts.\n\n## Running the Server\n\n### Stdio Mode (for Claude Desktop)\n\n```bash\nmake run-stdio\n# or\nuv run fastmcp run src/mcp_abstract_api/server.py\n```\n\n### HTTP Mode\n\n```bash\nmake run-http\n# or\nuv run uvicorn mcp_abstract_api.server:app --host 0.0.0.0 --port 8000\n\n# Test the server is running\nmake test-http\n```\n\n### Docker\n\n```bash\n# Build image locally\nmake docker-build\n\n# Build and push multi-platform image (amd64 + arm64)\nmake docker-buildx VERSION=1.0.0\n\n# Run container\nmake docker-run\n```\n\n## Claude Desktop Configuration\n\nAdd to your Claude Desktop config file:\n\n**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`\n**Windows**: `%APPDATA%/Claude/claude_desktop_config.json`\n\n### Option 1: HTTP Mode (Recommended)\n\nFirst, start the HTTP server:\n```bash\nmake run-http\n```\n\nThen add this to your Claude Desktop config:\n```json\n{\n  \"mcpServers\": {\n    \"abstract-api\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"mcp-remote\",\n        \"http://localhost:8000/mcp\"\n      ]\n    }\n  }\n}\n```\n\n**Benefits**: Better performance, easier debugging, can be deployed remotely\n\n### Option 2: Stdio Mode\n\n```json\n{\n  \"mcpServers\": {\n    \"abstract-api\": {\n      \"command\": \"uv\",\n      \"args\": [\n        \"--directory\",\n        \"/absolute/path/to/mcp-abstract-api\",\n        \"run\",\n        \"fastmcp\",\n        \"run\",\n        \"src/mcp_abstract_api/server.py\"\n      ]\n    }\n  }\n}\n```\n\n**Note**: With stdio mode, the `.env` file in the project directory will be automatically loaded. With HTTP mode, ensure the server is running in the correct directory or that environment variables are set.\n\n## Available MCP Tools\n\n### Email Validation\n- `validate_email(email)` - Validate email and check deliverability\n\n### Phone Validation\n- `validate_phone(phone, country_code?)` - Validate phone number\n\n### VAT Validation\n- `validate_vat(vat_number)` - Validate EU VAT number\n\n### IP Intelligence\n- `geolocate_ip(ip_address, fields?)` - Get location from IP\n- `get_ip_info(ip_address)` - Get detailed IP information\n- `geolocate_ip_security(ip_address)` - Get IP location with security/threat analysis\n\n### Time \u0026 Location\n- `get_timezone(location?, latitude?, longitude?)` - Get timezone info\n- `convert_timezone(base_location, base_datetime, target_location)` - Convert time\n- `get_holidays(country, year, month?, day?)` - Get public holidays\n\n### Financial\n- `get_exchange_rates(base, target?)` - Get currency exchange rates\n- `convert_currency(base, target, amount, date?)` - Convert currency\n\n### Web \u0026 Business\n- `get_company_info(domain)` - Get company data from domain\n- `scrape_url(url, render_js?)` - Scrape web pages\n- `generate_screenshot(url, width?, height?, full_page?)` - Screenshot websites\n\n## Development\n\n### Quick Commands\n\n```bash\nmake help          # Show all available commands\nmake install       # Install dependencies\nmake dev-install   # Install with dev dependencies\nmake format        # Format code with ruff\nmake lint          # Lint code with ruff\nmake typecheck     # Type check with mypy\nmake test          # Run tests with pytest\nmake test-cov      # Run tests with coverage\nmake test-http     # Test HTTP server is running\nmake check         # Run all checks (lint + typecheck + test)\nmake clean         # Clean up artifacts\nmake all           # Full workflow (clean + install + format + check)\n```\n\n### Running Tests\n\n```bash\n# Run all tests\nmake test\n\n# Run with coverage report\nmake test-cov\n\n# Run specific test file\nuv run pytest tests/test_server.py -v\n```\n\n### Code Quality\n\n```bash\n# Format code\nmake format\n\n# Lint code\nmake lint\n\n# Fix linting issues automatically\nmake lint-fix\n\n# Type check\nmake typecheck\n\n# Run all checks\nmake check\n```\n\n### Docker Commands\n\n```bash\n# Build local image\nmake docker-build\n\n# Build and push multi-platform image\nmake docker-buildx VERSION=1.0.0\n\n# Run container\nmake docker-run\n```\n\n**Multi-Platform Build Setup** (first time only):\n\n```bash\n# Create and use a new buildx builder\ndocker buildx create --name multiplatform --use\n\n# Verify the builder\ndocker buildx inspect --bootstrap\n```\n\nThe `docker-buildx` command builds for both `linux/amd64` and `linux/arm64` architectures and pushes directly to your container registry.\n\n## Project Structure\n\n```\n.\n├── src/\n│   └── mcp_abstract_api/\n│       ├── __init__.py\n│       ├── server.py          # FastMCP server with tool definitions\n│       ├── api_client.py      # Async API client class\n│       └── api_models.py      # Pydantic models for type safety\n├── tests/\n│   ├── __init__.py\n│   ├── test_server.py         # Server tool tests\n│   └── test_api_client.py     # API client tests\n├── pyproject.toml             # Project config with dependencies\n├── Makefile                   # Development workflow commands\n├── Dockerfile                 # Container deployment\n├── pytest.ini                 # Pytest configuration\n├── .gitignore                 # Comprehensive ignores\n├── .python-version            # Python version (3.13)\n└── README.md                  # This file\n```\n\n## Architecture\n\nThis project follows the **S-Tier MCP Server Architecture**:\n\n- **Separation of Concerns**: API client, models, and server are separate\n- **Type Safety First**: Strong typing with Pydantic and mypy strict mode\n- **Async All the Way**: Async/await for all I/O operations\n- **Error Handling**: Custom exceptions, context logging, graceful failures\n- **Testability**: Mock-friendly design with dependency injection\n- **Production Ready**: Docker, health checks, monitoring support\n\n## Requirements\n\n- Python 3.13+\n- aiohttp\n- fastapi\n- fastmcp\n- pydantic\n\n## Health Check \u0026 Troubleshooting\n\nThe server exposes a health check endpoint at `/health`:\n\n```bash\ncurl http://localhost:8000/health\n# {\"status\":\"healthy\",\"service\":\"mcp-abstract-api\"}\n\n# Or use the Makefile command\nmake test-http\n```\n\n### Troubleshooting HTTP Mode\n\nIf Claude Desktop can't connect to the server:\n\n1. **Check server is running**: `make test-http`\n2. **Verify port**: Ensure port 8000 is not in use by another service\n3. **Check logs**: Look at the server output for any errors\n4. **Test MCP endpoint**: `curl http://localhost:8000/` should return MCP protocol info\n5. **Verify .env**: Ensure `ABSTRACT_API_KEY` is set in your `.env` file\n\n### Changing the Port\n\nTo use a different port (e.g., 9000):\n\n```bash\nuv run uvicorn mcp_abstract_api.server:app --host 0.0.0.0 --port 9000\n```\n\nThen update your Claude Desktop config to use `http://localhost:9000/mcp`\n\n## Error Handling\n\nAll API errors are wrapped in `AbstractAPIError` with:\n- HTTP status code\n- Error message\n- Optional error details\n\nErrors are logged via the MCP context for debugging.\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Run `make check` to ensure quality\n5. Submit a pull request\n\n\n\n## Support\n\nFor issues, questions, or contributions, please open an issue on GitHub.\n\n## License\n\nMIT License - see LICENSE file for details\n\n## Links\n\nPart of the [NimbleTools Registry](https://github.com/nimbletoolsinc/mcp-registry) - an open source collection of production-ready MCP servers. For enterprise deployment, check out [NimbleBrain](https://www.nimblebrain.ai).\n\n- [Abstract API Documentation](https://www.abstractapi.com/api)\n- [FastMCP Documentation](https://github.com/jlowin/fastmcp)\n- [MCP Documentation](https://modelcontextprotocol.io)","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FNimbleBrainInc%2Fmcp-abstract","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FNimbleBrainInc%2Fmcp-abstract","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FNimbleBrainInc%2Fmcp-abstract/lists"}