ipinfo-mcp-server 0.2.0__tar.gz → 0.2.2__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (60) hide show
  1. {ipinfo_mcp_server-0.2.0 → ipinfo_mcp_server-0.2.2}/.github/workflows/codeql.yml +2 -2
  2. ipinfo_mcp_server-0.2.2/.github/workflows/release.yml +56 -0
  3. {ipinfo_mcp_server-0.2.0 → ipinfo_mcp_server-0.2.2}/.github/workflows/scorecard.yml +1 -1
  4. {ipinfo_mcp_server-0.2.0 → ipinfo_mcp_server-0.2.2}/PKG-INFO +6 -8
  5. {ipinfo_mcp_server-0.2.0 → ipinfo_mcp_server-0.2.2}/README.md +5 -7
  6. {ipinfo_mcp_server-0.2.0 → ipinfo_mcp_server-0.2.2}/manifest.json +1 -1
  7. {ipinfo_mcp_server-0.2.0 → ipinfo_mcp_server-0.2.2}/pyproject.toml +1 -1
  8. {ipinfo_mcp_server-0.2.0 → ipinfo_mcp_server-0.2.2}/server.json +3 -20
  9. {ipinfo_mcp_server-0.2.0 → ipinfo_mcp_server-0.2.2}/src/ipinfo_mcp/errors.py +16 -5
  10. {ipinfo_mcp_server-0.2.0 → ipinfo_mcp_server-0.2.2}/src/ipinfo_mcp/landing.html +125 -87
  11. {ipinfo_mcp_server-0.2.0 → ipinfo_mcp_server-0.2.2}/src/ipinfo_mcp/server.py +12 -1
  12. {ipinfo_mcp_server-0.2.0 → ipinfo_mcp_server-0.2.2}/src/ipinfo_mcp/tools/asn.py +2 -1
  13. {ipinfo_mcp_server-0.2.0 → ipinfo_mcp_server-0.2.2}/src/ipinfo_mcp/tools/geolocate.py +2 -1
  14. {ipinfo_mcp_server-0.2.0 → ipinfo_mcp_server-0.2.2}/src/ipinfo_mcp/tools/lookup.py +2 -1
  15. {ipinfo_mcp_server-0.2.0 → ipinfo_mcp_server-0.2.2}/src/ipinfo_mcp/tools/privacy.py +2 -1
  16. {ipinfo_mcp_server-0.2.0 → ipinfo_mcp_server-0.2.2}/src/ipinfo_mcp/tools/quota.py +1 -0
  17. {ipinfo_mcp_server-0.2.0 → ipinfo_mcp_server-0.2.2}/src/ipinfo_mcp/tools/resproxy.py +2 -1
  18. {ipinfo_mcp_server-0.2.0 → ipinfo_mcp_server-0.2.2}/tests/tools/test_asn.py +4 -4
  19. {ipinfo_mcp_server-0.2.0 → ipinfo_mcp_server-0.2.2}/tests/tools/test_geolocate.py +4 -4
  20. {ipinfo_mcp_server-0.2.0 → ipinfo_mcp_server-0.2.2}/tests/tools/test_lookup.py +39 -5
  21. {ipinfo_mcp_server-0.2.0 → ipinfo_mcp_server-0.2.2}/tests/tools/test_privacy.py +4 -4
  22. {ipinfo_mcp_server-0.2.0 → ipinfo_mcp_server-0.2.2}/tests/tools/test_quota.py +1 -1
  23. {ipinfo_mcp_server-0.2.0 → ipinfo_mcp_server-0.2.2}/tests/tools/test_resproxy.py +4 -4
  24. {ipinfo_mcp_server-0.2.0 → ipinfo_mcp_server-0.2.2}/uv.lock +5 -5
  25. {ipinfo_mcp_server-0.2.0 → ipinfo_mcp_server-0.2.2}/.dockerignore +0 -0
  26. {ipinfo_mcp_server-0.2.0 → ipinfo_mcp_server-0.2.2}/.env.example +0 -0
  27. {ipinfo_mcp_server-0.2.0 → ipinfo_mcp_server-0.2.2}/.github/dependabot.yml +0 -0
  28. {ipinfo_mcp_server-0.2.0 → ipinfo_mcp_server-0.2.2}/.github/workflows/build.yml +0 -0
  29. {ipinfo_mcp_server-0.2.0 → ipinfo_mcp_server-0.2.2}/.github/workflows/mcp-registry.yml +0 -0
  30. {ipinfo_mcp_server-0.2.0 → ipinfo_mcp_server-0.2.2}/.github/workflows/pypi.yml +0 -0
  31. {ipinfo_mcp_server-0.2.0 → ipinfo_mcp_server-0.2.2}/.github/workflows/test.yml +0 -0
  32. {ipinfo_mcp_server-0.2.0 → ipinfo_mcp_server-0.2.2}/.gitignore +0 -0
  33. {ipinfo_mcp_server-0.2.0 → ipinfo_mcp_server-0.2.2}/.mcpbignore +0 -0
  34. {ipinfo_mcp_server-0.2.0 → ipinfo_mcp_server-0.2.2}/CONTRIBUTING.md +0 -0
  35. {ipinfo_mcp_server-0.2.0 → ipinfo_mcp_server-0.2.2}/Dockerfile +0 -0
  36. {ipinfo_mcp_server-0.2.0 → ipinfo_mcp_server-0.2.2}/LICENSE.txt +0 -0
  37. {ipinfo_mcp_server-0.2.0 → ipinfo_mcp_server-0.2.2}/SECURITY.md +0 -0
  38. {ipinfo_mcp_server-0.2.0 → ipinfo_mcp_server-0.2.2}/assets/logo-dark.png +0 -0
  39. {ipinfo_mcp_server-0.2.0 → ipinfo_mcp_server-0.2.2}/assets/logo-light.png +0 -0
  40. {ipinfo_mcp_server-0.2.0 → ipinfo_mcp_server-0.2.2}/src/ipinfo_mcp/__init__.py +0 -0
  41. {ipinfo_mcp_server-0.2.0 → ipinfo_mcp_server-0.2.2}/src/ipinfo_mcp/__main__.py +0 -0
  42. {ipinfo_mcp_server-0.2.0 → ipinfo_mcp_server-0.2.2}/src/ipinfo_mcp/auth.py +0 -0
  43. {ipinfo_mcp_server-0.2.0 → ipinfo_mcp_server-0.2.2}/src/ipinfo_mcp/cache.py +0 -0
  44. {ipinfo_mcp_server-0.2.0 → ipinfo_mcp_server-0.2.2}/src/ipinfo_mcp/client.py +0 -0
  45. {ipinfo_mcp_server-0.2.0 → ipinfo_mcp_server-0.2.2}/src/ipinfo_mcp/logging.py +0 -0
  46. {ipinfo_mcp_server-0.2.0 → ipinfo_mcp_server-0.2.2}/src/ipinfo_mcp/pagination.py +0 -0
  47. {ipinfo_mcp_server-0.2.0 → ipinfo_mcp_server-0.2.2}/src/ipinfo_mcp/params.py +0 -0
  48. {ipinfo_mcp_server-0.2.0 → ipinfo_mcp_server-0.2.2}/src/ipinfo_mcp/tools/__init__.py +0 -0
  49. {ipinfo_mcp_server-0.2.0 → ipinfo_mcp_server-0.2.2}/src/ipinfo_mcp/types.py +0 -0
  50. {ipinfo_mcp_server-0.2.0 → ipinfo_mcp_server-0.2.2}/src/ipinfo_mcp/validation.py +0 -0
  51. {ipinfo_mcp_server-0.2.0 → ipinfo_mcp_server-0.2.2}/tests/__init__.py +0 -0
  52. {ipinfo_mcp_server-0.2.0 → ipinfo_mcp_server-0.2.2}/tests/conftest.py +0 -0
  53. {ipinfo_mcp_server-0.2.0 → ipinfo_mcp_server-0.2.2}/tests/integration/__init__.py +0 -0
  54. {ipinfo_mcp_server-0.2.0 → ipinfo_mcp_server-0.2.2}/tests/integration/test_client.py +0 -0
  55. {ipinfo_mcp_server-0.2.0 → ipinfo_mcp_server-0.2.2}/tests/test_auth.py +0 -0
  56. {ipinfo_mcp_server-0.2.0 → ipinfo_mcp_server-0.2.2}/tests/test_cache.py +0 -0
  57. {ipinfo_mcp_server-0.2.0 → ipinfo_mcp_server-0.2.2}/tests/test_client.py +0 -0
  58. {ipinfo_mcp_server-0.2.0 → ipinfo_mcp_server-0.2.2}/tests/test_pagination.py +0 -0
  59. {ipinfo_mcp_server-0.2.0 → ipinfo_mcp_server-0.2.2}/tests/test_validation.py +0 -0
  60. {ipinfo_mcp_server-0.2.0 → ipinfo_mcp_server-0.2.2}/tests/tools/__init__.py +0 -0
@@ -35,13 +35,13 @@ jobs:
35
35
  persist-credentials: false
36
36
 
37
37
  - name: Initialize CodeQL
38
- uses: github/codeql-action/init@24c54180a607b1449ed407dd24f251e4e9147c8d # v4.38.3
38
+ uses: github/codeql-action/init@6f2ac81f5cd81fe351a197ba0b00d91d03cd2aee # v4.39.0
39
39
  with:
40
40
  languages: ${{ matrix.language }}
41
41
  build-mode: none
42
42
  queries: security-and-quality
43
43
 
44
44
  - name: Perform CodeQL analysis
45
- uses: github/codeql-action/analyze@24c54180a607b1449ed407dd24f251e4e9147c8d # v4.38.3
45
+ uses: github/codeql-action/analyze@6f2ac81f5cd81fe351a197ba0b00d91d03cd2aee # v4.39.0
46
46
  with:
47
47
  category: "/language:${{ matrix.language }}"
@@ -0,0 +1,56 @@
1
+ name: "Release: Prepare"
2
+
3
+ on:
4
+ workflow_dispatch:
5
+ inputs:
6
+ version:
7
+ description: "Version to release, e.g. 1.2.3"
8
+ required: true
9
+ type: string
10
+
11
+ permissions:
12
+ contents: read
13
+
14
+ jobs:
15
+ bump:
16
+ runs-on: ubuntu-latest
17
+ permissions: {}
18
+ steps:
19
+ - name: Check version
20
+ env:
21
+ VERSION: ${{ inputs.version }}
22
+ run: |
23
+ if [[ ! "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
24
+ echo "::error::Version must look like 1.2.3, got: $VERSION"
25
+ exit 1
26
+ fi
27
+
28
+ - name: Checkout repo
29
+ uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
30
+ with:
31
+ ref: main
32
+ token: ${{ secrets.RELEASE_PR_TOKEN }}
33
+
34
+ - name: Install uv
35
+ uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884 # v10.3.0
36
+
37
+ - name: Bump version
38
+ env:
39
+ VERSION: ${{ inputs.version }}
40
+ run: |
41
+ old=$(uv version --short)
42
+ uv version "$VERSION" --no-sync
43
+ sed -i "s/\"version\": \"$old\"/\"version\": \"$VERSION\"/" manifest.json server.json
44
+
45
+ - name: Open pull request
46
+ env:
47
+ GH_TOKEN: ${{ secrets.RELEASE_PR_TOKEN }}
48
+ VERSION: ${{ inputs.version }}
49
+ run: |
50
+ git switch -c "release/v$VERSION"
51
+ git -c user.name="github-actions[bot]" \
52
+ -c user.email="41898282+github-actions[bot]@users.noreply.github.com" \
53
+ commit -am "Bump version to $VERSION"
54
+ git push origin "release/v$VERSION"
55
+ gh pr create --base main --title "Bump version to $VERSION" \
56
+ --body "After merging, push the \`v$VERSION\` tag to publish the release."
@@ -73,6 +73,6 @@ jobs:
73
73
  # Upload the results to GitHub's code scanning dashboard (optional).
74
74
  # Commenting out will disable upload of results to your repo's Code Scanning dashboard
75
75
  - name: "Upload to code-scanning"
76
- uses: github/codeql-action/upload-sarif@24c54180a607b1449ed407dd24f251e4e9147c8d # v4.38.3
76
+ uses: github/codeql-action/upload-sarif@6f2ac81f5cd81fe351a197ba0b00d91d03cd2aee # v4.39.0
77
77
  with:
78
78
  sarif_file: results.sarif
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: ipinfo-mcp-server
3
- Version: 0.2.0
3
+ Version: 0.2.2
4
4
  Summary: Official IPinfo MCP Server - IP intelligence tools for AI assistants
5
5
  Author-email: IPinfo <support@ipinfo.io>
6
6
  License-Expression: Apache-2.0
@@ -31,19 +31,15 @@ For the full guide, see the [official documentation](https://ipinfo.io/developer
31
31
 
32
32
  ## Installation
33
33
 
34
- All tools require an IPinfo API token. Get a free one at [ipinfo.io/signup](https://ipinfo.io/signup).
34
+ You need an IPinfo account. Sign up for free at [ipinfo.io/signup](https://ipinfo.io/signup).
35
35
 
36
36
  ### Hosted server
37
37
 
38
- Point your MCP client at `https://mcp.ipinfo.io/` (Streamable HTTP) and send your token as a bearer credential:
39
-
40
- ```
41
- Authorization: Bearer <your-ipinfo-token>
42
- ```
38
+ Point your MCP client at `https://mcp.ipinfo.io/` (Streamable HTTP). The first time it connects, it asks you to sign in with your IPinfo account through OAuth.
43
39
 
44
40
  ### Local server (PyPI)
45
41
 
46
- The server is published on PyPI as [`ipinfo-mcp-server`](https://pypi.org/project/ipinfo-mcp-server/) and runs over stdio. With [uv](https://docs.astral.sh/uv/) installed, add it to your MCP client configuration:
42
+ The server is published on PyPI as [`ipinfo-mcp-server`](https://pypi.org/project/ipinfo-mcp-server/) and runs over stdio, authenticating with your [API token](https://ipinfo.io/account/token). With [uv](https://docs.astral.sh/uv/) installed, add it to your MCP client configuration:
47
43
 
48
44
  ```json
49
45
  {
@@ -67,6 +63,8 @@ Download `mcp.mcpb` from the [latest GitHub release](https://github.com/ipinfo/m
67
63
 
68
64
  The server is listed in the [MCP Registry](https://registry.modelcontextprotocol.io/) as `io.github.ipinfo/mcp`.
69
65
 
66
+ The server is also listed on [LightNow](https://lightnow.ai/servers/io.github.ipinfo/mcp).
67
+
70
68
  ## Tools
71
69
 
72
70
  | Tool | Description | Plan requirement |
@@ -14,19 +14,15 @@ For the full guide, see the [official documentation](https://ipinfo.io/developer
14
14
 
15
15
  ## Installation
16
16
 
17
- All tools require an IPinfo API token. Get a free one at [ipinfo.io/signup](https://ipinfo.io/signup).
17
+ You need an IPinfo account. Sign up for free at [ipinfo.io/signup](https://ipinfo.io/signup).
18
18
 
19
19
  ### Hosted server
20
20
 
21
- Point your MCP client at `https://mcp.ipinfo.io/` (Streamable HTTP) and send your token as a bearer credential:
22
-
23
- ```
24
- Authorization: Bearer <your-ipinfo-token>
25
- ```
21
+ Point your MCP client at `https://mcp.ipinfo.io/` (Streamable HTTP). The first time it connects, it asks you to sign in with your IPinfo account through OAuth.
26
22
 
27
23
  ### Local server (PyPI)
28
24
 
29
- The server is published on PyPI as [`ipinfo-mcp-server`](https://pypi.org/project/ipinfo-mcp-server/) and runs over stdio. With [uv](https://docs.astral.sh/uv/) installed, add it to your MCP client configuration:
25
+ The server is published on PyPI as [`ipinfo-mcp-server`](https://pypi.org/project/ipinfo-mcp-server/) and runs over stdio, authenticating with your [API token](https://ipinfo.io/account/token). With [uv](https://docs.astral.sh/uv/) installed, add it to your MCP client configuration:
30
26
 
31
27
  ```json
32
28
  {
@@ -50,6 +46,8 @@ Download `mcp.mcpb` from the [latest GitHub release](https://github.com/ipinfo/m
50
46
 
51
47
  The server is listed in the [MCP Registry](https://registry.modelcontextprotocol.io/) as `io.github.ipinfo/mcp`.
52
48
 
49
+ The server is also listed on [LightNow](https://lightnow.ai/servers/io.github.ipinfo/mcp).
50
+
53
51
  ## Tools
54
52
 
55
53
  | Tool | Description | Plan requirement |
@@ -2,7 +2,7 @@
2
2
  "manifest_version": "0.4",
3
3
  "name": "ipinfo-mcp-server",
4
4
  "display_name": "IPinfo",
5
- "version": "0.2.0",
5
+ "version": "0.2.2",
6
6
  "description": "IP address intelligence tools: geolocation, ASN, privacy detection, residential proxy checks, and more.",
7
7
  "author": {
8
8
  "name": "IPinfo",
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
6
  name = "ipinfo-mcp-server"
7
- version = "0.2.0"
7
+ version = "0.2.2"
8
8
  description = "Official IPinfo MCP Server - IP intelligence tools for AI assistants"
9
9
  readme = "README.md"
10
10
  license = "Apache-2.0"
@@ -3,7 +3,7 @@
3
3
  "name": "io.github.ipinfo/mcp",
4
4
  "title": "IPinfo",
5
5
  "description": "Official IPinfo MCP Server - IP intelligence tools for AI assistants",
6
- "version": "0.2.0",
6
+ "version": "0.2.2",
7
7
  "websiteUrl": "https://ipinfo.io",
8
8
  "repository": {
9
9
  "url": "https://github.com/ipinfo/mcp",
@@ -26,7 +26,7 @@
26
26
  "registryType": "pypi",
27
27
  "registryBaseUrl": "https://pypi.org",
28
28
  "identifier": "ipinfo-mcp-server",
29
- "version": "0.2.0",
29
+ "version": "0.2.2",
30
30
  "runtimeHint": "uvx",
31
31
  "transport": {
32
32
  "type": "stdio"
@@ -45,24 +45,7 @@
45
45
  "remotes": [
46
46
  {
47
47
  "type": "streamable-http",
48
- "url": "https://mcp.ipinfo.io/",
49
- "headers": [
50
- {
51
- "name": "Authorization",
52
- "description": "Your IPinfo API token as a bearer credential. Get a free one at https://ipinfo.io/signup",
53
- "isRequired": true,
54
- "isSecret": true,
55
- "value": "Bearer {ipinfo_token}",
56
- "variables": {
57
- "ipinfo_token": {
58
- "description": "Your IPinfo API token",
59
- "isRequired": true,
60
- "isSecret": true,
61
- "format": "string"
62
- }
63
- }
64
- }
65
- ]
48
+ "url": "https://mcp.ipinfo.io/"
66
49
  }
67
50
  ]
68
51
  }
@@ -38,11 +38,17 @@ _MESSAGE_ERROR_CODES_MAPPING: list[tuple[str, ErrorCode]] = [
38
38
  ]
39
39
 
40
40
  _SUGGESTIONS: dict[ErrorCode, str] = {
41
- "ACCESS_DENIED": "Tell the user they can get access by upgrading at https://ipinfo.io/pricing",
42
- "RATE_LIMITED": "Tell the user they can upgrade their tier at https://ipinfo.io/pricing",
41
+ "ACCESS_DENIED": (
42
+ "The user's IPinfo plan doesn't include this data. "
43
+ "The data each plan includes is listed at https://ipinfo.io/pricing"
44
+ ),
45
+ "RATE_LIMITED": (
46
+ "The user's IPinfo plan has reached its request limit, try again later. "
47
+ "The limits of each plan are listed at https://ipinfo.io/pricing"
48
+ ),
43
49
  "INVALID_TOKEN": "Tell the user to check their token at https://ipinfo.io/account/token",
44
50
  "NO_TOKEN": "The user didn't set IPINFO_TOKEN. They can get a free token at https://ipinfo.io/signup",
45
- "UNKNOWN": "An unforseen error happened, tell the user to report it to https://ipinfo.io/",
51
+ "UNKNOWN": "An unexpected error happened, tell the user to contact IPinfo support at support@ipinfo.io",
46
52
  }
47
53
 
48
54
 
@@ -105,19 +111,24 @@ def handle_api_error(
105
111
  return ErrorResponse(
106
112
  code="ACCESS_DENIED",
107
113
  message=message,
108
- suggestion="Tell the user they can get access by upgrading at https://ipinfo.io/pricing",
114
+ suggestion=_SUGGESTIONS["ACCESS_DENIED"],
109
115
  )
110
116
 
111
117
  if status == 429:
112
118
  return ErrorResponse(
113
119
  code="RATE_LIMITED",
114
120
  message="Rate limit exceeded.",
115
- suggestion="Tell the user they can upgrade their tier at https://ipinfo.io/pricing",
121
+ suggestion=_SUGGESTIONS["RATE_LIMITED"],
116
122
  )
117
123
 
118
124
  return ErrorResponse(
119
125
  code="API_ERROR",
120
126
  message=f"IPinfo API returned status {status}.",
127
+ suggestion=(
128
+ "The IPinfo API is having a temporary problem, try the request again in a moment"
129
+ if status >= 500
130
+ else _SUGGESTIONS["UNKNOWN"]
131
+ ),
121
132
  )
122
133
 
123
134
 
@@ -1,5 +1,5 @@
1
1
  <!doctype html>
2
- <html lang="en">
2
+ <html lang="en" data-auth="token">
3
3
  <head>
4
4
  <meta charset="utf-8" />
5
5
  <meta name="viewport" content="width=device-width, initial-scale=1" />
@@ -232,6 +232,12 @@
232
232
  display: block;
233
233
  }
234
234
 
235
+ /* The server sets data-auth to oauth when OAuth is on */
236
+ [data-auth="oauth"] .token-only,
237
+ [data-auth="token"] .oauth-only {
238
+ display: none;
239
+ }
240
+
235
241
  /* Token input */
236
242
  .token-row {
237
243
  display: flex;
@@ -422,14 +428,19 @@
422
428
  <div class="section">
423
429
  <h2>Connect</h2>
424
430
  <p style="margin-bottom: 0.75rem">
425
- Point your MCP client to this URL:
431
+ Point your MCP client to this URL<span class="oauth-only">
432
+ and sign in with your IPinfo account when it asks</span
433
+ >:
426
434
  </p>
427
435
  <div class="copy-wrapper">
428
436
  <pre><code id="mcp-url"></code></pre>
429
437
  <button class="copy-btn" data-copy="mcp-url">Copy</button>
430
438
  </div>
431
439
  <p class="signup-cta">
432
- Get a free API token at
440
+ <span class="oauth-only"
441
+ >No IPinfo account yet? Sign up free at</span
442
+ >
443
+ <span class="token-only">Get a free API token at</span>
433
444
  <a href="https://ipinfo.io/signup">ipinfo.io/signup</a>
434
445
  </p>
435
446
  </div>
@@ -437,7 +448,7 @@
437
448
  <div class="section">
438
449
  <h2>Client Setup</h2>
439
450
 
440
- <div class="token-row">
451
+ <div class="token-row token-only">
441
452
  <label for="token-input">API Token</label>
442
453
  <input
443
454
  id="token-input"
@@ -502,69 +513,82 @@
502
513
  class="accordion-content"
503
514
  id="accordion-claude-desktop"
504
515
  >
505
- <div class="install-section">
506
- <div class="install-badges">
507
- <a
508
- href="https://github.com/ipinfo/mcp/releases/latest/download/mcp.mcpb"
509
- class="install-btn install-btn-claude"
510
- >
511
- <svg
512
- width="14"
513
- height="14"
514
- viewBox="0 0 12 12"
515
- fill="none"
516
- xmlns="http://www.w3.org/2000/svg"
516
+ <div class="oauth-only">
517
+ <p class="panel-header">
518
+ Open Settings &rarr; Connectors &rarr; Add
519
+ custom connector and paste the URL above.
520
+ </p>
521
+ <p class="panel-note">
522
+ Then sign in with your IPinfo account when
523
+ Claude asks.
524
+ </p>
525
+ </div>
526
+ <div class="token-only">
527
+ <div class="install-section">
528
+ <div class="install-badges">
529
+ <a
530
+ href="https://github.com/ipinfo/mcp/releases/latest/download/mcp.mcpb"
531
+ class="install-btn install-btn-claude"
517
532
  >
518
- <g
519
- clip-path="url(#claude-desktop-clip)"
533
+ <svg
534
+ width="14"
535
+ height="14"
536
+ viewBox="0 0 12 12"
537
+ fill="none"
538
+ xmlns="http://www.w3.org/2000/svg"
520
539
  >
521
- <path
522
- d="m2.96 7.65 1.97-1.1.03-.1-.03-.05h-.1l-.33-.02-1.12-.03-.97-.04-.95-.06-.24-.05L1 5.91l.02-.15.2-.13.29.02.63.05.95.06.69.04 1.02.11h.16L5 5.84l-.06-.04-.04-.04-.99-.66-1.06-.7-.56-.41-.3-.2-.15-.2-.07-.42.28-.3.36.03.1.02.37.29.8.61 1.03.77.16.12.06-.04v-.03l-.06-.11-.57-1.02-.6-1.04-.27-.43-.07-.26c-.03-.1-.04-.2-.04-.3l.3-.42L3.8 1l.42.06.17.15.26.59.42.93.64 1.26.2.37.1.35.03.1h.07v-.06l.05-.7.1-.88.1-1.12.03-.32.16-.38.3-.2.25.11.2.29-.03.18-.12.77-.23 1.21-.15.81h.09l.1-.1.41-.54.69-.86.3-.34.36-.38.22-.18h.43l.32.47-.14.49-.44.56-.37.47-.53.71-.33.57.03.04h.08l1.2-.26.63-.11.77-.13.35.16.04.16-.14.34-.82.2-.96.2-1.44.33-.01.01.02.03.64.06.28.02h.68l1.25.09.33.22.2.26-.03.2-.5.26-.7-.16-1.59-.38-.54-.13h-.08v.04l.46.45.83.75 1.05.97.05.24-.13.2-.15-.03-.92-.69-.35-.31-.8-.68h-.06v.08l.19.27.98 1.46.05.45-.07.15-.26.09-.28-.05-.57-.8-.59-.9-.47-.82-.06.04-.28 3.02-.13.15-.3.12-.26-.2-.14-.3.14-.62.16-.8.13-.64.12-.79.07-.26v-.02H5.9l-.6.83-.9 1.22-.73.77-.17.07-.3-.15.03-.28.17-.24 1-1.27.6-.78.38-.46v-.06h-.03L2.72 8.73l-.47.06-.2-.19.02-.3.1-.1.8-.55Z"
523
- fill="#fff"
524
- ></path>
525
- </g>
526
- <defs>
527
- <clipPath
528
- id="claude-desktop-clip"
540
+ <g
541
+ clip-path="url(#claude-desktop-clip)"
529
542
  >
530
543
  <path
544
+ d="m2.96 7.65 1.97-1.1.03-.1-.03-.05h-.1l-.33-.02-1.12-.03-.97-.04-.95-.06-.24-.05L1 5.91l.02-.15.2-.13.29.02.63.05.95.06.69.04 1.02.11h.16L5 5.84l-.06-.04-.04-.04-.99-.66-1.06-.7-.56-.41-.3-.2-.15-.2-.07-.42.28-.3.36.03.1.02.37.29.8.61 1.03.77.16.12.06-.04v-.03l-.06-.11-.57-1.02-.6-1.04-.27-.43-.07-.26c-.03-.1-.04-.2-.04-.3l.3-.42L3.8 1l.42.06.17.15.26.59.42.93.64 1.26.2.37.1.35.03.1h.07v-.06l.05-.7.1-.88.1-1.12.03-.32.16-.38.3-.2.25.11.2.29-.03.18-.12.77-.23 1.21-.15.81h.09l.1-.1.41-.54.69-.86.3-.34.36-.38.22-.18h.43l.32.47-.14.49-.44.56-.37.47-.53.71-.33.57.03.04h.08l1.2-.26.63-.11.77-.13.35.16.04.16-.14.34-.82.2-.96.2-1.44.33-.01.01.02.03.64.06.28.02h.68l1.25.09.33.22.2.26-.03.2-.5.26-.7-.16-1.59-.38-.54-.13h-.08v.04l.46.45.83.75 1.05.97.05.24-.13.2-.15-.03-.92-.69-.35-.31-.8-.68h-.06v.08l.19.27.98 1.46.05.45-.07.15-.26.09-.28-.05-.57-.8-.59-.9-.47-.82-.06.04-.28 3.02-.13.15-.3.12-.26-.2-.14-.3.14-.62.16-.8.13-.64.12-.79.07-.26v-.02H5.9l-.6.83-.9 1.22-.73.77-.17.07-.3-.15.03-.28.17-.24 1-1.27.6-.78.38-.46v-.06h-.03L2.72 8.73l-.47.06-.2-.19.02-.3.1-.1.8-.55Z"
531
545
  fill="#fff"
532
- transform="translate(1 1)"
533
- d="M0 0h10v10H0z"
534
546
  ></path>
535
- </clipPath>
536
- </defs>
537
- </svg>
538
- Download MCPB
539
- </a>
547
+ </g>
548
+ <defs>
549
+ <clipPath
550
+ id="claude-desktop-clip"
551
+ >
552
+ <path
553
+ fill="#fff"
554
+ transform="translate(1 1)"
555
+ d="M0 0h10v10H0z"
556
+ ></path>
557
+ </clipPath>
558
+ </defs>
559
+ </svg>
560
+ Download MCPB
561
+ </a>
562
+ </div>
540
563
  </div>
564
+ <p class="panel-header">
565
+ Add to
566
+ <span class="inline-code"
567
+ >claude_desktop_config.json</span
568
+ >
569
+ &mdash; macOS:
570
+ <span class="inline-code"
571
+ >~/Library/Application
572
+ Support/Claude/</span
573
+ >
574
+ &bull; Windows:
575
+ <span class="inline-code"
576
+ >%APPDATA%\Claude\</span
577
+ >
578
+ </p>
579
+ <div class="panel-copy">
580
+ <pre><code id="cfg-claude-desktop"></code></pre>
581
+ <button
582
+ class="copy-btn"
583
+ data-copy="cfg-claude-desktop"
584
+ >
585
+ Copy
586
+ </button>
587
+ </div>
588
+ <p class="panel-note">
589
+ Restart Claude Desktop after saving.
590
+ </p>
541
591
  </div>
542
- <p class="panel-header">
543
- Add to
544
- <span class="inline-code"
545
- >claude_desktop_config.json</span
546
- >
547
- &mdash; macOS:
548
- <span class="inline-code"
549
- >~/Library/Application Support/Claude/</span
550
- >
551
- &bull; Windows:
552
- <span class="inline-code"
553
- >%APPDATA%\Claude\</span
554
- >
555
- </p>
556
- <div class="panel-copy">
557
- <pre><code id="cfg-claude-desktop"></code></pre>
558
- <button
559
- class="copy-btn"
560
- data-copy="cfg-claude-desktop"
561
- >
562
- Copy
563
- </button>
564
- </div>
565
- <p class="panel-note">
566
- Restart Claude Desktop after saving.
567
- </p>
568
592
  </div>
569
593
  </div>
570
594
 
@@ -809,8 +833,11 @@
809
833
  </div>
810
834
  </div>
811
835
  <p class="panel-note" style="padding-top: 0.5rem">
812
- Opens VS Code and installs the server with your
813
- token prefilled. Requires VS Code 1.99+.
836
+ Opens VS Code and installs the server<span
837
+ class="token-only"
838
+ >
839
+ with your token prefilled</span
840
+ >. Requires VS Code 1.99+.
814
841
  </p>
815
842
  <hr class="panel-divider" />
816
843
  <p class="manual-label">
@@ -949,8 +976,11 @@
949
976
  </div>
950
977
  </div>
951
978
  <p class="panel-note" style="padding-top: 0.5rem">
952
- Opens Cursor and installs the server with your
953
- token prefilled.
979
+ Opens Cursor and installs the server<span
980
+ class="token-only"
981
+ >
982
+ with your token prefilled</span
983
+ >.
954
984
  </p>
955
985
  <hr class="panel-divider" />
956
986
  <p class="manual-label">
@@ -1271,6 +1301,11 @@
1271
1301
  <span class="inline-code">--scope project</span>
1272
1302
  to add it only to the current project, or omit
1273
1303
  for the global config.
1304
+ <span class="oauth-only"
1305
+ >Then run
1306
+ <span class="inline-code">/mcp</span> in
1307
+ Claude Code to sign in.</span
1308
+ >
1274
1309
  </p>
1275
1310
  </div>
1276
1311
  </div>
@@ -1392,12 +1427,18 @@
1392
1427
 
1393
1428
  <script>
1394
1429
  const BASE_URL = window.location.origin + "/";
1430
+ const OAUTH = document.documentElement.dataset.auth === "oauth";
1395
1431
  const TOKEN_PLACEHOLDER = "<IPINFO_TOKEN>";
1396
1432
 
1397
1433
  document.getElementById("mcp-url").textContent = BASE_URL;
1398
1434
 
1399
1435
  // ── Config generators ────────────────────────────────────────────────────
1400
1436
 
1437
+ // Without a token the client signs in with OAuth, so no header is sent.
1438
+ function authHeaders(tok) {
1439
+ return tok ? { Authorization: "Bearer " + tok } : undefined;
1440
+ }
1441
+
1401
1442
  function cfgClaudeDesktop(url, tok) {
1402
1443
  return JSON.stringify(
1403
1444
  {
@@ -1430,9 +1471,7 @@
1430
1471
  ipinfo: {
1431
1472
  type: "http",
1432
1473
  url: url,
1433
- headers: {
1434
- Authorization: "Bearer " + tok,
1435
- },
1474
+ headers: authHeaders(tok),
1436
1475
  },
1437
1476
  },
1438
1477
  },
@@ -1445,10 +1484,7 @@
1445
1484
  return JSON.stringify(
1446
1485
  {
1447
1486
  mcpServers: {
1448
- ipinfo: {
1449
- url: url,
1450
- headers: { Authorization: "Bearer " + tok },
1451
- },
1487
+ ipinfo: { url: url, headers: authHeaders(tok) },
1452
1488
  },
1453
1489
  },
1454
1490
  null,
@@ -1458,10 +1494,7 @@
1458
1494
 
1459
1495
  function cfgLMStudio(url, tok) {
1460
1496
  return JSON.stringify(
1461
- {
1462
- url: url,
1463
- headers: { Authorization: "Bearer " + tok },
1464
- },
1497
+ { url: url, headers: authHeaders(tok) },
1465
1498
  null,
1466
1499
  2,
1467
1500
  );
@@ -1471,10 +1504,7 @@
1471
1504
  return JSON.stringify(
1472
1505
  {
1473
1506
  mcpServers: {
1474
- ipinfo: {
1475
- httpUrl: url,
1476
- headers: { Authorization: "Bearer " + tok },
1477
- },
1507
+ ipinfo: { httpUrl: url, headers: authHeaders(tok) },
1478
1508
  },
1479
1509
  },
1480
1510
  null,
@@ -1483,9 +1513,12 @@
1483
1513
  }
1484
1514
 
1485
1515
  function cfgClaudeCode(url, tok) {
1516
+ const cmd = "claude mcp add --transport http ipinfo " + url;
1517
+ if (!tok) {
1518
+ return cmd;
1519
+ }
1486
1520
  return (
1487
- "claude mcp add --transport http ipinfo " +
1488
- url +
1521
+ cmd +
1489
1522
  " \\\n" +
1490
1523
  ' --header "Authorization: Bearer ' +
1491
1524
  tok +
@@ -1494,13 +1527,18 @@
1494
1527
  }
1495
1528
 
1496
1529
  function cfgCodex(url, tok) {
1497
- return (
1530
+ const cfg =
1498
1531
  "[mcp_servers.ipinfo]\n" +
1499
1532
  'transport = "http"\n' +
1500
1533
  'url = "' +
1501
1534
  url +
1502
- '"\n\n' +
1503
- "[mcp_servers.ipinfo.headers]\n" +
1535
+ '"';
1536
+ if (!tok) {
1537
+ return cfg;
1538
+ }
1539
+ return (
1540
+ cfg +
1541
+ "\n\n[mcp_servers.ipinfo.headers]\n" +
1504
1542
  'Authorization = "Bearer ' +
1505
1543
  tok +
1506
1544
  '"'
@@ -1516,7 +1554,7 @@
1516
1554
  function deepLinkCursor(url, tok) {
1517
1555
  const cfg = JSON.stringify({
1518
1556
  url: url,
1519
- headers: { Authorization: "Bearer " + tok },
1557
+ headers: authHeaders(tok),
1520
1558
  });
1521
1559
  return (
1522
1560
  "cursor://anysphere.cursor-deeplink/mcp/install?name=ipinfo&config=" +
@@ -1529,7 +1567,7 @@
1529
1567
  name: "ipinfo",
1530
1568
  type: "http",
1531
1569
  url: url,
1532
- headers: { Authorization: "Bearer " + tok },
1570
+ headers: authHeaders(tok),
1533
1571
  };
1534
1572
  const scheme = insiders ? "vscode-insiders" : "vscode";
1535
1573
  return (
@@ -1542,7 +1580,7 @@
1542
1580
  function deepLinkLMStudio(url, tok) {
1543
1581
  const cfg = JSON.stringify({
1544
1582
  url: url,
1545
- headers: { Authorization: "Bearer " + tok },
1583
+ headers: authHeaders(tok),
1546
1584
  });
1547
1585
  return "lmstudio://add_mcp?name=ipinfo&config=" + b64(cfg);
1548
1586
  }
@@ -1560,7 +1598,7 @@
1560
1598
  };
1561
1599
 
1562
1600
  function renderAll(tok) {
1563
- const t = tok || TOKEN_PLACEHOLDER;
1601
+ const t = OAUTH ? "" : tok || TOKEN_PLACEHOLDER;
1564
1602
  for (const [id, fn] of Object.entries(generators)) {
1565
1603
  document.getElementById(id).textContent = fn(BASE_URL, t);
1566
1604
  }
@@ -113,7 +113,18 @@ register_geolocate(mcp)
113
113
  register_asn(mcp)
114
114
  register_quota(mcp)
115
115
 
116
- _LANDING_HTML = (Path(__file__).parent / "landing.html").read_text()
116
+
117
+ def _landing_html(*, oauth: bool) -> str:
118
+ """
119
+ Render the landing page, with OAuth setup instructions or API token ones.
120
+ """
121
+ html = (Path(__file__).parent / "landing.html").read_text()
122
+ if oauth:
123
+ html = html.replace('<html lang="en" data-auth="token">', '<html lang="en" data-auth="oauth">', 1)
124
+ return html
125
+
126
+
127
+ _LANDING_HTML = _landing_html(oauth=mcp.auth is not None)
117
128
 
118
129
 
119
130
  class LandingPageMiddleware:
@@ -49,7 +49,7 @@ async def ipinfo_asn(
49
49
  "Which IPinfo endpoint to query. Leave false to use the Lite endpoint, which "
50
50
  "returns the ASN, name, and domain. Set to true to use the full lookup endpoint, "
51
51
  "which also returns the network type (isp, hosting, business, education) and when "
52
- "the AS record last changed; it requires a token whose plan includes that data, "
52
+ "the AS record last changed; it requires an IPinfo plan that includes that data, "
53
53
  "otherwise the call fails with ACCESS_DENIED."
54
54
  )
55
55
  ),
@@ -159,6 +159,7 @@ def register_asn(mcp: FastMCP) -> None:
159
159
  """Register the ipinfo_asn tool with the MCP server."""
160
160
  _ = mcp.tool(
161
161
  annotations=ToolAnnotations(
162
+ title="ASN Lookup",
162
163
  read_only_hint=True,
163
164
  destructive_hint=False,
164
165
  idempotent_hint=True,
@@ -55,7 +55,7 @@ async def ipinfo_geolocate(
55
55
  "Which IPinfo endpoint to query. Leave false to use the Lite endpoint, which "
56
56
  "returns country and continent only. Set to true to use the full lookup endpoint, "
57
57
  "which also returns city, region, latitude and longitude, timezone, and postal "
58
- "code; it requires a token whose plan includes that data, otherwise the call "
58
+ "code; it requires an IPinfo plan that includes that data, otherwise the call "
59
59
  "fails with ACCESS_DENIED."
60
60
  )
61
61
  ),
@@ -172,6 +172,7 @@ def register_geolocate(mcp: FastMCP) -> None:
172
172
  """Register the ipinfo_geolocate tool with the MCP server."""
173
173
  _ = mcp.tool(
174
174
  annotations=ToolAnnotations(
175
+ title="IP Geolocation",
175
176
  read_only_hint=True,
176
177
  destructive_hint=False,
177
178
  idempotent_hint=True,
@@ -39,7 +39,7 @@ async def ipinfo_lookup(
39
39
  "Which IPinfo endpoint to query. Leave false to use the Lite endpoint, which "
40
40
  "returns country, continent, and basic ASN. Set to true to use the full lookup "
41
41
  "endpoint, which also returns city-level geolocation, privacy flags (VPN, proxy, "
42
- "Tor, hosting, anycast), and richer AS data; it requires a token whose plan "
42
+ "Tor, hosting, anycast), and richer AS data; it requires an IPinfo plan that "
43
43
  "includes that data, otherwise the call fails with ACCESS_DENIED."
44
44
  )
45
45
  ),
@@ -130,6 +130,7 @@ def register_lookup(mcp: FastMCP) -> None:
130
130
  """Register the ipinfo_lookup tool with the MCP server."""
131
131
  _ = mcp.tool(
132
132
  annotations=ToolAnnotations(
133
+ title="IP Lookup",
133
134
  read_only_hint=True,
134
135
  destructive_hint=False,
135
136
  idempotent_hint=True,
@@ -52,7 +52,7 @@ async def ipinfo_check_privacy(
52
52
  Returns privacy flags for each IP: whether it is anonymous, using a VPN, proxy,
53
53
  relay, or Tor, and whether it is an anycast, hosting, mobile, or satellite address.
54
54
 
55
- Requires a paid API token. Results are paginated.
55
+ Requires an IPinfo plan that includes privacy detection. Results are paginated.
56
56
 
57
57
  If the API reports an error for specific IPs, those IPs are listed in errors
58
58
  with the reason and left out of results. Do not treat a missing result as
@@ -152,6 +152,7 @@ def register_privacy(mcp: FastMCP) -> None:
152
152
  """Register the ipinfo_check_privacy tool with the MCP server."""
153
153
  _ = mcp.tool(
154
154
  annotations=ToolAnnotations(
155
+ title="Privacy Detection",
155
156
  read_only_hint=True,
156
157
  destructive_hint=False,
157
158
  idempotent_hint=True,
@@ -41,6 +41,7 @@ def register_quota(mcp: FastMCP) -> None:
41
41
  """Register the ipinfo_quota tool with the MCP server."""
42
42
  _ = mcp.tool(
43
43
  annotations=ToolAnnotations(
44
+ title="API Quota",
44
45
  read_only_hint=True,
45
46
  destructive_hint=False,
46
47
  idempotent_hint=True,
@@ -49,7 +49,7 @@ async def ipinfo_check_residential_proxy(
49
49
  Returns whether each IP is a residential proxy and, if so, the proxy service name,
50
50
  the date it was last seen, and the percentage of days the IP was observed as a proxy.
51
51
 
52
- Requires a paid API token with residential proxy access. Results are paginated.
52
+ Requires an IPinfo plan with residential proxy access. Results are paginated.
53
53
 
54
54
  If the API reports an error for specific IPs, those IPs are listed in errors
55
55
  with the reason and left out of results. Do not treat a missing result as
@@ -137,6 +137,7 @@ def register_resproxy(mcp: FastMCP) -> None:
137
137
  """Register the ipinfo_check_residential_proxy tool with the MCP server."""
138
138
  _ = mcp.tool(
139
139
  annotations=ToolAnnotations(
140
+ title="Residential Proxy Detection",
140
141
  read_only_hint=True,
141
142
  destructive_hint=False,
142
143
  idempotent_hint=True,
@@ -142,7 +142,7 @@ class TestAsnErrors:
142
142
  assert result["errors"]["8.8.8.8"] == {
143
143
  "code": "ACCESS_DENIED",
144
144
  "message": "Token does not have access to this API",
145
- "suggestion": "Tell the user they can get access by upgrading at https://ipinfo.io/pricing",
145
+ "suggestion": "The user's IPinfo plan doesn't include this data. The data each plan includes is listed at https://ipinfo.io/pricing",
146
146
  }
147
147
 
148
148
  async def test_per_key_error_is_not_cached(
@@ -179,7 +179,7 @@ class TestAsnErrors:
179
179
  assert result["errors"]["8.8.8.8"] == {
180
180
  "code": "UNKNOWN",
181
181
  "message": "The server exploded",
182
- "suggestion": "An unforseen error happened, tell the user to report it to https://ipinfo.io/",
182
+ "suggestion": "An unexpected error happened, tell the user to contact IPinfo support at support@ipinfo.io",
183
183
  }
184
184
 
185
185
  async def test_partial_error_still_returns_good_ips(
@@ -203,7 +203,7 @@ class TestAsnErrors:
203
203
  assert result["errors"]["1.1.1.1"] == {
204
204
  "code": "ACCESS_DENIED",
205
205
  "message": "Token does not have access to this API",
206
- "suggestion": "Tell the user they can get access by upgrading at https://ipinfo.io/pricing",
206
+ "suggestion": "The user's IPinfo plan doesn't include this data. The data each plan includes is listed at https://ipinfo.io/pricing",
207
207
  }
208
208
 
209
209
  async def test_403_returns_access_denied(
@@ -220,7 +220,7 @@ class TestAsnErrors:
220
220
  )
221
221
 
222
222
  assert result["message"] == "You don't have access to ASN lookup."
223
- assert result["suggestion"] == "Tell the user they can get access by upgrading at https://ipinfo.io/pricing"
223
+ assert result["suggestion"] == "The user's IPinfo plan doesn't include this data. The data each plan includes is listed at https://ipinfo.io/pricing"
224
224
  assert result["code"] == "ACCESS_DENIED"
225
225
 
226
226
  async def test_no_token_returns_error(
@@ -142,7 +142,7 @@ class TestGeolocateErrors:
142
142
  assert result["errors"]["8.8.8.8"] == {
143
143
  "code": "ACCESS_DENIED",
144
144
  "message": "Token does not have access to this API",
145
- "suggestion": "Tell the user they can get access by upgrading at https://ipinfo.io/pricing",
145
+ "suggestion": "The user's IPinfo plan doesn't include this data. The data each plan includes is listed at https://ipinfo.io/pricing",
146
146
  }
147
147
 
148
148
  async def test_per_key_error_is_not_cached(
@@ -179,7 +179,7 @@ class TestGeolocateErrors:
179
179
  assert result["errors"]["8.8.8.8"] == {
180
180
  "code": "UNKNOWN",
181
181
  "message": "The server exploded",
182
- "suggestion": "An unforseen error happened, tell the user to report it to https://ipinfo.io/",
182
+ "suggestion": "An unexpected error happened, tell the user to contact IPinfo support at support@ipinfo.io",
183
183
  }
184
184
 
185
185
  async def test_partial_error_still_returns_good_ips(
@@ -203,7 +203,7 @@ class TestGeolocateErrors:
203
203
  assert result["errors"]["1.1.1.1"] == {
204
204
  "code": "ACCESS_DENIED",
205
205
  "message": "Token does not have access to this API",
206
- "suggestion": "Tell the user they can get access by upgrading at https://ipinfo.io/pricing",
206
+ "suggestion": "The user's IPinfo plan doesn't include this data. The data each plan includes is listed at https://ipinfo.io/pricing",
207
207
  }
208
208
 
209
209
  async def test_403_returns_access_denied(
@@ -221,7 +221,7 @@ class TestGeolocateErrors:
221
221
 
222
222
  assert result["code"] == "ACCESS_DENIED"
223
223
  assert result["message"] == "You don't have access to geolocation."
224
- assert result["suggestion"] == "Tell the user they can get access by upgrading at https://ipinfo.io/pricing"
224
+ assert result["suggestion"] == "The user's IPinfo plan doesn't include this data. The data each plan includes is listed at https://ipinfo.io/pricing"
225
225
 
226
226
  async def test_no_token_returns_error(
227
227
  self, cache: IPCache, httpx_mock: HTTPXMock
@@ -249,7 +249,7 @@ class TestLookupErrors:
249
249
  assert result["errors"]["8.8.8.8"] == {
250
250
  "code": "ACCESS_DENIED",
251
251
  "message": "Token does not have access to this API",
252
- "suggestion": "Tell the user they can get access by upgrading at https://ipinfo.io/pricing",
252
+ "suggestion": "The user's IPinfo plan doesn't include this data. The data each plan includes is listed at https://ipinfo.io/pricing",
253
253
  }
254
254
 
255
255
  async def test_per_key_error_is_not_cached(
@@ -286,7 +286,7 @@ class TestLookupErrors:
286
286
  assert result["errors"]["8.8.8.8"] == {
287
287
  "code": "UNKNOWN",
288
288
  "message": "The server exploded",
289
- "suggestion": "An unforseen error happened, tell the user to report it to https://ipinfo.io/",
289
+ "suggestion": "An unexpected error happened, tell the user to contact IPinfo support at support@ipinfo.io",
290
290
  }
291
291
 
292
292
  async def test_partial_error_still_returns_good_ips(
@@ -310,7 +310,7 @@ class TestLookupErrors:
310
310
  assert result["errors"]["1.1.1.1"] == {
311
311
  "code": "RATE_LIMITED",
312
312
  "message": "You've reached your limit on this API",
313
- "suggestion": "Tell the user they can upgrade their tier at https://ipinfo.io/pricing",
313
+ "suggestion": "The user's IPinfo plan has reached its request limit, try again later. The limits of each plan are listed at https://ipinfo.io/pricing",
314
314
  }
315
315
 
316
316
  async def test_403_returns_access_denied(
@@ -328,7 +328,7 @@ class TestLookupErrors:
328
328
 
329
329
  assert result["code"] == "ACCESS_DENIED"
330
330
  assert result["message"] == "You don't have access to lookup."
331
- assert result["suggestion"] == "Tell the user they can get access by upgrading at https://ipinfo.io/pricing"
331
+ assert result["suggestion"] == "The user's IPinfo plan doesn't include this data. The data each plan includes is listed at https://ipinfo.io/pricing"
332
332
 
333
333
  async def test_401_returns_invalid_token(
334
334
  self, client: IPinfoClient, cache: IPCache, httpx_mock: HTTPXMock
@@ -363,7 +363,41 @@ class TestLookupErrors:
363
363
 
364
364
  assert result["code"] == "RATE_LIMITED"
365
365
  assert result["message"] == "Rate limit exceeded."
366
- assert result["suggestion"] == "Tell the user they can upgrade their tier at https://ipinfo.io/pricing"
366
+ assert result["suggestion"] == "The user's IPinfo plan has reached its request limit, try again later. The limits of each plan are listed at https://ipinfo.io/pricing"
367
+
368
+ async def test_5xx_returns_api_error_with_retry_suggestion(
369
+ self, client: IPinfoClient, cache: IPCache, httpx_mock: HTTPXMock
370
+ ) -> None:
371
+ httpx_mock.add_response(
372
+ url=f"{BASE_URL}/batch",
373
+ method="POST",
374
+ status_code=503,
375
+ )
376
+ ctx = make_context(client, cache)
377
+ result = await ipinfo_lookup(
378
+ ips=["8.8.8.8"], detailed=False, page=1, page_size=5, ctx=ctx
379
+ )
380
+
381
+ assert result["code"] == "API_ERROR"
382
+ assert result["message"] == "IPinfo API returned status 503."
383
+ assert result["suggestion"] == "The IPinfo API is having a temporary problem, try the request again in a moment"
384
+
385
+ async def test_other_4xx_returns_api_error_with_report_suggestion(
386
+ self, client: IPinfoClient, cache: IPCache, httpx_mock: HTTPXMock
387
+ ) -> None:
388
+ httpx_mock.add_response(
389
+ url=f"{BASE_URL}/batch",
390
+ method="POST",
391
+ status_code=400,
392
+ )
393
+ ctx = make_context(client, cache)
394
+ result = await ipinfo_lookup(
395
+ ips=["8.8.8.8"], detailed=False, page=1, page_size=5, ctx=ctx
396
+ )
397
+
398
+ assert result["code"] == "API_ERROR"
399
+ assert result["message"] == "IPinfo API returned status 400."
400
+ assert result["suggestion"] == "An unexpected error happened, tell the user to contact IPinfo support at support@ipinfo.io"
367
401
 
368
402
  async def test_no_token_returns_error(
369
403
  self, cache: IPCache, httpx_mock: HTTPXMock
@@ -170,7 +170,7 @@ class TestPrivacyErrors:
170
170
  assert result["errors"]["8.8.8.8"] == {
171
171
  "code": "ACCESS_DENIED",
172
172
  "message": "Token does not have access to this API",
173
- "suggestion": "Tell the user they can get access by upgrading at https://ipinfo.io/pricing",
173
+ "suggestion": "The user's IPinfo plan doesn't include this data. The data each plan includes is listed at https://ipinfo.io/pricing",
174
174
  }
175
175
 
176
176
  async def test_per_key_error_is_not_cached(
@@ -207,7 +207,7 @@ class TestPrivacyErrors:
207
207
  assert result["errors"]["8.8.8.8"] == {
208
208
  "code": "UNKNOWN",
209
209
  "message": "The server exploded",
210
- "suggestion": "An unforseen error happened, tell the user to report it to https://ipinfo.io/",
210
+ "suggestion": "An unexpected error happened, tell the user to contact IPinfo support at support@ipinfo.io",
211
211
  }
212
212
 
213
213
  async def test_partial_error_still_returns_good_ips(
@@ -231,7 +231,7 @@ class TestPrivacyErrors:
231
231
  assert result["errors"]["1.2.3.4"] == {
232
232
  "code": "ACCESS_DENIED",
233
233
  "message": "Token does not have access to this API",
234
- "suggestion": "Tell the user they can get access by upgrading at https://ipinfo.io/pricing",
234
+ "suggestion": "The user's IPinfo plan doesn't include this data. The data each plan includes is listed at https://ipinfo.io/pricing",
235
235
  }
236
236
 
237
237
  async def test_403_returns_access_denied(
@@ -249,7 +249,7 @@ class TestPrivacyErrors:
249
249
 
250
250
  assert result["code"] == "ACCESS_DENIED"
251
251
  assert result["message"] == "You don't have access to privacy detection."
252
- assert result["suggestion"] == "Tell the user they can get access by upgrading at https://ipinfo.io/pricing"
252
+ assert result["suggestion"] == "The user's IPinfo plan doesn't include this data. The data each plan includes is listed at https://ipinfo.io/pricing"
253
253
 
254
254
  async def test_no_token_returns_error(
255
255
  self, cache: IPCache, httpx_mock: HTTPXMock
@@ -77,7 +77,7 @@ class TestQuotaErrors:
77
77
 
78
78
  assert result["code"] == "ACCESS_DENIED"
79
79
  assert result["message"] == "You don't have access to quota."
80
- assert result["suggestion"] == "Tell the user they can get access by upgrading at https://ipinfo.io/pricing"
80
+ assert result["suggestion"] == "The user's IPinfo plan doesn't include this data. The data each plan includes is listed at https://ipinfo.io/pricing"
81
81
 
82
82
  async def test_401_returns_invalid_token(
83
83
  self, client: IPinfoClient, cache: IPCache, httpx_mock: HTTPXMock
@@ -107,7 +107,7 @@ class TestResproxyErrors:
107
107
  assert result["errors"]["8.8.8.8"] == {
108
108
  "code":"ACCESS_DENIED",
109
109
  "message": "Token does not have access to this API",
110
- "suggestion": "Tell the user they can get access by upgrading at https://ipinfo.io/pricing",
110
+ "suggestion": "The user's IPinfo plan doesn't include this data. The data each plan includes is listed at https://ipinfo.io/pricing",
111
111
  }
112
112
 
113
113
  async def test_per_key_error_is_not_cached(
@@ -148,7 +148,7 @@ class TestResproxyErrors:
148
148
  assert result["errors"]["8.8.8.8"] == {
149
149
  "code": "UNKNOWN",
150
150
  "message": "The server exploded",
151
- "suggestion": "An unforseen error happened, tell the user to report it to https://ipinfo.io/",
151
+ "suggestion": "An unexpected error happened, tell the user to contact IPinfo support at support@ipinfo.io",
152
152
  }
153
153
 
154
154
 
@@ -173,7 +173,7 @@ class TestResproxyErrors:
173
173
  assert result["errors"]["8.8.8.8"] == {
174
174
  "code": "ACCESS_DENIED",
175
175
  "message": "Token does not have access to this API",
176
- "suggestion": "Tell the user they can get access by upgrading at https://ipinfo.io/pricing",
176
+ "suggestion": "The user's IPinfo plan doesn't include this data. The data each plan includes is listed at https://ipinfo.io/pricing",
177
177
  }
178
178
 
179
179
  async def test_403_returns_access_denied(
@@ -190,7 +190,7 @@ class TestResproxyErrors:
190
190
  )
191
191
 
192
192
  assert result["message"] == "You don't have access to residential proxy detection."
193
- assert result["suggestion"] == "Tell the user they can get access by upgrading at https://ipinfo.io/pricing"
193
+ assert result["suggestion"] == "The user's IPinfo plan doesn't include this data. The data each plan includes is listed at https://ipinfo.io/pricing"
194
194
  assert result["code"] == "ACCESS_DENIED"
195
195
 
196
196
  async def test_no_token_returns_error(
@@ -1,5 +1,5 @@
1
1
  version = 1
2
- revision = 3
2
+ revision = 5
3
3
  requires-python = ">=3.14"
4
4
  resolution-markers = [
5
5
  "python_full_version >= '3.15'",
@@ -460,7 +460,7 @@ wheels = [
460
460
 
461
461
  [[package]]
462
462
  name = "ipinfo-mcp-server"
463
- version = "0.2.0"
463
+ version = "0.2.2"
464
464
  source = { editable = "." }
465
465
  dependencies = [
466
466
  { name = "fastmcp" },
@@ -539,14 +539,14 @@ wheels = [
539
539
 
540
540
  [[package]]
541
541
  name = "joserfc"
542
- version = "1.7.5"
542
+ version = "1.7.7"
543
543
  source = { registry = "https://pypi.org/simple" }
544
544
  dependencies = [
545
545
  { name = "cryptography" },
546
546
  ]
547
- sdist = { url = "https://files.pythonhosted.org/packages/19/94/80fea1514b7c6d7d37804d3fe9ca81455f633347fc98731bd71ffe1faa17/joserfc-1.7.5.tar.gz", hash = "sha256:d5ff536e658e17664f8c1b1ab60dc4aa62aa973fcef1edd33cc44bda45d6f5ea", size = 234990, upload-time = "2026-08-29T13:05:42.057Z" }
547
+ sdist = { url = "https://files.pythonhosted.org/packages/bd/15/48ff246732232d35ee234228def22b52455fcc55577f06146602399a29b0/joserfc-1.7.7.tar.gz", hash = "sha256:471d0fd12a5a0d1c0942de280f39efe6f597878315033270b504d4d006d25510", size = 237446, upload-time = "2026-10-19T00:30:29.974Z" }
548
548
  wheels = [
549
- { url = "https://files.pythonhosted.org/packages/67/c5/82addfd375e5ee6520644e0553e4aadde92d668c4fc99cc716d337fe7bb3/joserfc-1.7.5-py3-none-any.whl", hash = "sha256:add2c2c84e8373b084d526a8b53daba5d7a513a118cd2dcd9fc9f979d0922159", size = 71269, upload-time = "2026-08-29T13:05:40.718Z" },
549
+ { url = "https://files.pythonhosted.org/packages/df/9f/934db284aa22f37af59708e382903860d4b81329c137b1b0ed2745daeb65/joserfc-1.7.7-py3-none-any.whl", hash = "sha256:06979cfbab78bc802f14c0358f32969826cc26720e13cb38926ffdc86bc0cb2c", size = 71758, upload-time = "2026-10-19T00:30:28.498Z" },
550
550
  ]
551
551
 
552
552
  [[package]]