# onecall-mcp

**An MCP (Model Context Protocol) server exposing 10 production-tested no-auth public APIs as tools for AI agents.**

Built on top of [onecall](https://github.com/Matrix-ops77/onecall). Zero API keys. Stdlib Python. MIT.

```
weather_current(location)              # wttr.in
weather_forecast(lat, lon, days)       # open-meteo
fx_convert(amount, from, to)           # frankfurter (ECB)
fx_rates(base, symbols)                # frankfurter
crypto_price(ids, vs_currency)         # coingecko
geocode(query, limit)                  # openstreetmap nominatim
country_info(query)                    # REST Countries
time_in_zone(timezone)                 # timeapi.io
hn_front()                             # Hacker News top 10
hn_search(query, limit)                # Hacker News Algolia search
```

## Why this exists

Most AI agents need to call weather, FX, crypto, geocoding, time, country, and news lookups. The data is on the open web for free. But the agent needs **tools**, not URLs. This server gives any MCP-compatible client (Claude Desktop, Cursor, Windsurf, Cline, OpenAI Codex CLI, etc.) all 10 in one process.

## Install

### Claude Desktop
Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
```json
{
  "mcpServers": {
    "onecall": {
      "command": "python3",
      "args": ["/path/to/onecall-mcp/src/onecall_mcp_server.py"]
    }
  }
}
```

### Cursor
Settings → Features → Model Context Protocol → Add new global MCP server. Same command/args.

### Windsurf / Cline / others
Same shape — `command` is the python interpreter, `args` is the absolute path to `onecall_mcp_server.py`.

## Verify

```bash
# End-to-end JSON-RPC over stdio test
bash tests/mcp_stdio_smoke.sh
```

Last run: **10/10 PASS** (2026-08-26). Initialize, tools/list, tools/call all return correct JSON-RPC 2.0 with live API data.

## Architecture

- **stdlib only.** No `mcp` package dependency, no `requests`, no SDK. Just `urllib` + `json` + `asyncio`.
- **stdio JSON-RPC 2.0.** Per MCP spec 2024-11-05.
- **Reuses onecall's `_lib/http.py`** for retries, URL encoding, uniform envelope.
- **`--demo` flag** prints the tool catalog + runs one live call, useful for sanity checks.

## Smoke-test receipts (2026-08-26)

```
=== Passed: 10  Failed: 0 ===
```

10 assertions covering: protocol handshake, capability negotiation, tool discovery, tool invocation, live API response.

## Roadmap

- [ ] Add the remaining 4 onecall wrappers (sunrise, catfact, cataas, nager holidays)
- [ ] HTTP transport (currently stdio only)
- [ ] Per-call usage tracking + x402 stablecoin paywall integration
- [ ] Listing on glama.ai, smithery.ai, mcpmarket.com, mcpservers.org

## License

MIT.