io.github.ktozvonil/phone-lookup
Who-called phone lookups: community verdict, spam rating, operator and reviews (ktozvonil.net).
Open source Repository Open in the app JSON README (API)
About
Who-called phone lookups: community verdict, spam rating, operator and reviews (ktozvonil.net).
Details
- Kind
- MCP servers
- Topic
- No topic detected
- Publisher
- ktozvonil
- Origin
- official
- Category
- ferramentas
- Transport
- http
- Version
- 1.0.2
- Last push
- 2026-08-05T17:44:31Z
- Repository state
- ativo
- Language
- JavaScript
- License
- MIT
- Added
- 2026-08-29 04:00:22
- Updated
- 2026-08-29 04:00:22
- Origin id
io.github.ktozvonil/phone-lookup
README
# mcp-server-ktozvonil
MCP (Model Context Protocol) server for **[ktozvonil.net](https://ktozvonil.net)** — a community phone-number reputation service for Ukraine and beyond. Ask your AI assistant *"who called me from 050 110 89 01?"* and it will answer with the community verdict, spam rating, operator, region, tags and recent reviews.
This package is a thin stdio bridge to the site's native MCP endpoint (`https://ktozvonil.net/mcp`). Tools are discovered at startup, so the package never goes stale.
## Tools
| Tool | Description | Auth |
|------|-------------|------|
| `lookup_phone` | Community verdict, rating, spam level, operator, region, tags and recent reviews for a number | none |
| `post_comment` | Post a review on behalf of an authenticated user (labelled as AI-agent-generated, shown separately, does not affect the community rating) | OAuth bearer |
## Install
### Claude Code
```bash
claude mcp add ktozvonil -- npx -y mcp-server-ktozvonil
```
### Claude Desktop
```json
{
"mcpServers": {
"ktozvonil": {
"command": "npx",
"args": ["-y", "mcp-server-ktozvonil"]
}
}
}
```
### Cursor / Windsurf / other MCP clients
Any client that speaks stdio MCP works the same way: command `npx`, args `-y mcp-server-ktozvonil`.
### Remote (no install)
MCP clients that support remote servers can skip this package entirely and connect straight to:
```
https://ktozvonil.net/mcp
```
## Configuration
| Env var | Meaning |
|---------|---------|
| `KTOZVONIL_MCP_URL` | Override the endpoint URL (default `https://ktozvonil.net/mcp`) |
| `KTOZVONIL_TOKEN` | OAuth bearer token — only needed for `post_comment`. Discovery: [`/.well-known/oauth-protected-resource`](https://ktozvonil.net/.well-known/oauth-protected-resource) |
## Example
> **User:** Кто звонил с +38 050 110 89 01?
>
> **Assistant:** *(calls `lookup_phone`)* This number has a "spam" community verdict on ktozvonil.net: 78 reports, mostly "intrusive advertising"…
## Development
```bash
npm install
npm run build
npm test
```
## Related
- [ktozvonil.net](https://ktozvonil.net) — the service itself (uk/ru/en + 5 more languages)
- [`ua-phone`](https://github.com/ktozvonil/ua-phone) — Ukrainian phone number parsing/formatting library
- API docs: [ktozvonil.net/.well-known/api-catalog](https://ktozvonil.net/.well-known/api-catalog)
## License
MIT © [ktozvonil.net](https://ktozvonil.net)