@moonbanking/mcp-server 1.2.0 → 1.7.0

package/.github/workflows/npm-publish.yml

@@ -169,39 +169,124 @@ jobs:
           token: ${{ secrets.SYNC_DOCS_TOKEN }}
           path: moonbanking
 
-      - name: Update documentation
+      - name: Update main MCP documentation
+        shell: bash
         run: |
           # Create the target directory if it doesn't exist
           mkdir -p moonbanking/apps/docs/app/mcp
-          
+
           # Create the new content with prepended metadata
           cat > moonbanking/apps/docs/app/mcp/page.mdx << 'EOF'
-          {/* 
-            DO NOT EDIT THIS FILE DIRECTLY! 
-          
+          {/*
+            DO NOT EDIT THIS FILE DIRECTLY!
+
             It is automatically generated by the npm-publish GitHub Action in
             the moonbanking/mcp-server repository.
           */}
-          
+
           export const metadata = {
             title: `MCP`,
             description: `Create AI agents using Moon Banking's MCP server. Get high-quality data about banks worldwide from your favorite LLM platform with Moon Banking's MCP.`,
           };
-          
-          <ApiKeyNote featureName="MCP" />
-          
+
           EOF
-          
+
           # Append the README content
           cat mcp-server/README.md >> moonbanking/apps/docs/app/mcp/page.mdx
-          
-          echo "✅ Documentation updated"
+
+          # Rewrite GitHub-relative markdown links so they resolve to docs-app routes:
+          #   ./README.md   → /mcp
+          #   ./<slug>.md   → /<slug>
+          # Also handles the bare-form variants (without `./`).
+          sed -i -E \
+            -e 's#\]\((\./)?README\.md\)#](/mcp)#g' \
+            -e 's#\]\((\./)?([A-Za-z][A-Za-z0-9-]*)\.md\)#](/\2)#g' \
+            moonbanking/apps/docs/app/mcp/page.mdx
+
+          echo "✅ Main MCP documentation updated"
+
+      - name: Update platform documentation
+        shell: bash
+        run: |
+          # Sync each per-platform doc page (e.g. mcp-server/cursor.md, which
+          # lives at the package root alongside README.md) into the docs app
+          # as a TOP-LEVEL route (apps/docs/app/cursor/page.mdx).
+          # Title + description are parsed from the markdown file itself, so
+          # adding a new platform in the moonbanking monorepo generator
+          # automatically flows through this workflow with no further edits.
+
+          shopt -s nullglob
+          synced=0
+
+          # Files we should NOT treat as platform docs even if they end in .md.
+          skip_regex='^(README|CHANGELOG|LICENSE|CONTRIBUTING|CODE_OF_CONDUCT|SECURITY)$'
+
+          for src in mcp-server/*.md; do
+            slug="$(basename "$src" .md)"
+
+            # Skip non-platform markdown at the package root.
+            if [[ "$slug" =~ $skip_regex ]]; then
+              echo "↪︎  Skipping $slug.md (non-platform file)"
+              continue
+            fi
+
+            # Extract `<Name>` from `# Moon Banking MCP for <Name>` (first H1).
+            title="$(sed -n 's/^# Moon Banking MCP for \(.*\)$/\1/p' "$src" | head -n1)"
+            # Extract description from the first `> ...` blockquote line.
+            description="$(sed -n 's/^> \(.*\)$/\1/p' "$src" | head -n1)"
+
+            # If the file doesn't look like a platform doc, bail rather than
+            # publish a malformed docs page.
+            if [ -z "$title" ]; then
+              echo "⚠️  ${slug}.md does not look like a platform doc (no '# Moon Banking MCP for ...' H1) — skipping."
+              continue
+            fi
+
+            if [ -z "$description" ]; then
+              description="Connect ${title} to the Moon Banking MCP server."
+            fi
+
+            dest_dir="moonbanking/apps/docs/app/$slug"
+            mkdir -p "$dest_dir"
+            dest="$dest_dir/page.mdx"
+
+            {
+              echo '{/*'
+              echo '  DO NOT EDIT THIS FILE DIRECTLY!'
+              echo ''
+              echo '  It is automatically generated by the npm-publish GitHub Action in'
+              echo '  the moonbanking/mcp-server repository.'
+              echo '*/}'
+              echo ''
+              echo 'export const metadata = {'
+              echo "  title: \`MCP — ${title}\`,"
+              echo "  description: \`${description}\`,"
+              echo '};'
+              echo ''
+            } > "$dest"
+
+            cat "$src" >> "$dest"
+
+            # Rewrite GitHub-relative markdown links so they resolve to
+            # docs-app routes:
+            #   ./README.md  → /mcp
+            #   ./<slug>.md  → /<slug>
+            sed -i -E \
+              -e 's#\]\((\./)?README\.md\)#](/mcp)#g' \
+              -e 's#\]\((\./)?([A-Za-z][A-Za-z0-9-]*)\.md\)#](/\2)#g' \
+              "$dest"
+
+            echo "✅ Synced ${slug}.md → apps/docs/app/${slug}/page.mdx"
+            synced=$((synced + 1))
+          done
+
+          echo "📚 ${synced} platform docs synced"
 
       - name: Check for changes
         id: check_changes
         run: |
           cd moonbanking
-          if git diff --quiet apps/docs/app/mcp/page.mdx; then
+          if [ -z "$(git status --porcelain apps/docs/app/)" ]; then
             echo "has_changes=false" >> $GITHUB_OUTPUT
             echo "ℹ️ No changes detected in documentation"
           else
@@ -221,16 +306,29 @@ jobs:
           title: 'docs: sync MCP documentation v${{ needs.publish.outputs.version }}'
           body: |
             ## 🔄 Automated Documentation Sync
-            
+
             This PR automatically syncs the MCP server documentation from the [mcp-server repository](https://github.com/moonbanking/mcp-server).
-            
+
             **Version:** v${{ needs.publish.outputs.version }}
-            **Source:** README.md from mcp-server
-            **Target:** apps/docs/app/mcp/page.mdx
-            
+
+            ### Sources → targets
+
+            | Source (mcp-server root) | Target (moonbanking docs) |
+            | --- | --- |
+            | `README.md` | `apps/docs/app/mcp/page.mdx` |
+            | `<slug>.md` (cursor, claude, …) | `apps/docs/app/<slug>/page.mdx` (top-level route, one per MCP client) |
+
+            ### Link rewriting
+
+            GitHub-relative markdown links inside the source files are rewritten at sync time so they resolve to docs-app routes:
+
+            - `./README.md` → `/mcp`
+            - `./<slug>.md` → `/<slug>`
+
             ### Changes
-            - Updated MCP documentation with latest content from mcp-server v${{ needs.publish.outputs.version }}
-            
+            - Updated main MCP documentation with latest content from mcp-server v${{ needs.publish.outputs.version }}
+            - Synced per-platform setup guides (Claude, Cursor, Grok, ChatGPT, VS Code, Windsurf, Zed, Claude Code, MCP Inspector, …) to their own top-level docs pages
+
             ---
             *This PR was automatically created by the npm-publish GitHub Action*
           labels: |
@@ -245,12 +343,13 @@ jobs:
             echo "Created pull request to sync MCP documentation to getfullup/moonbanking repository." >> $GITHUB_STEP_SUMMARY
             echo "" >> $GITHUB_STEP_SUMMARY
             echo "**Version:** v${{ needs.publish.outputs.version }}" >> $GITHUB_STEP_SUMMARY
-            echo "**Target File:** apps/docs/app/mcp/page.mdx" >> $GITHUB_STEP_SUMMARY
+            echo "**Targets:**" >> $GITHUB_STEP_SUMMARY
+            echo "- apps/docs/app/mcp/page.mdx (main MCP page from README.md)" >> $GITHUB_STEP_SUMMARY
+            echo "- apps/docs/app/<slug>/page.mdx (one per platform, from <slug>.md at package root)" >> $GITHUB_STEP_SUMMARY
           else
             echo "## ℹ️ No Documentation Changes" >> $GITHUB_STEP_SUMMARY
             echo "" >> $GITHUB_STEP_SUMMARY
             echo "Documentation is already up to date. No pull request created." >> $GITHUB_STEP_SUMMARY
             echo "" >> $GITHUB_STEP_SUMMARY
             echo "**Version:** v${{ needs.publish.outputs.version }}" >> $GITHUB_STEP_SUMMARY
-            echo "**Target File:** apps/docs/app/mcp/page.mdx" >> $GITHUB_STEP_SUMMARY
-          fi
+          fi

package/README.md

@@ -1,8 +1,72 @@
 # Moon Banking MCP Server
 
-The Moon Banking MCP server is generated from the [OpenAPI specification](https://github.com/moonbanking/moonbanking-openapi).
+Moon Banking is a global directory of consumer and business banks with structured, community-rated scores across 14 categories — customer service, fees & pricing, digital experience, crypto friendliness, security & trust, lending, business banking, international banking, transparency, and more. The Moon Banking MCP server exposes that entire dataset — every bank, country, score, vote, and user story — as live tools your AI agent can call, so answers about real-world banking are grounded in fresh Moon Banking data instead of stale training-set guesses.
 
-## Installation
+Once connected, you can ask questions like *"which crypto-friendly banks operate in Brazil?"*, *"compare digital-experience scores for the top US challenger banks"*, or *"summarize recent user stories about fees at HSBC UK"* and get tool-grounded, citable answers backed by the same data that powers [moonbanking.com](https://moonbanking.com).
+
+The server is generated from the public [OpenAPI specification](https://github.com/moonbanking/moonbanking-openapi) and ships as both a hosted OAuth endpoint at `https://mcp.moonbanking.com/mcp` and a stdio npm package (`@moonbanking/mcp-server`) — so you can connect it to Claude, Cursor, Grok, ChatGPT, VS Code, Devin Desktop (formerly Windsurf), Zed, and any other [Model Context Protocol](https://modelcontextprotocol.io) client.
+
+## Client-specific setup guides
+
+If you just want to wire Moon Banking up to a specific client, jump straight to its guide. Each one covers both the hosted OAuth setup and the self-hosted stdio fallback.
+
+| Client | Guide |
+| --- | --- |
+| Claude (Desktop & web) | [claude](./claude.md) |
+| Claude Code | [claude-code](./claude-code.md) |
+| Cursor | [cursor](./cursor.md) |
+| Devin Desktop (formerly Windsurf) | [devin-desktop](./devin-desktop.md) |
+| VS Code (GitHub Copilot) | [vscode](./vscode.md) |
+| Zed | [zed](./zed.md) |
+| ChatGPT | [chatgpt](./chatgpt.md) |
+| Grok (xAI) | [grok](./grok.md) |
+| MCP Inspector (testing) | [mcp-inspector](./mcp-inspector.md) |
+
+The rest of this README covers the underlying authentication options and configuration shapes.
+
+## Authentication
+
+You can connect to Moon Banking over MCP using **either** of two auth methods:
+
+| Method | Best for | API key required? |
+| --- | --- | --- |
+| **Hosted OAuth server** (recommended) | Claude, Cursor, Grok, ChatGPT, and any MCP client that supports remote/streamable HTTP MCP. Users sign in to Moon Banking in a browser — no key handling. | No |
+| **Self-hosted stdio package** (this npm package) | Local scripts, agents, or clients that only support stdio MCP. | Yes |
+
+Both methods expose the same tool surface; pick whichever matches your client.
+
+## Hosted MCP server (OAuth)
+
+URL: `https://mcp.moonbanking.com/mcp` (Streamable HTTP, OAuth 2.0 with Dynamic Client Registration).
+
+Most modern MCP clients can connect by simply pointing at the URL — they will pop a browser window for the user to sign in to Moon Banking and obtain an access token automatically. No API key is exchanged or stored on the client side.
+
+```json
+{
+  "mcpServers": {
+    "moonbanking": {
+      "url": "https://mcp.moonbanking.com/mcp"
+    }
+  }
+}
+```
+
+For clients that don't yet speak remote MCP natively (eg. older ChatGPT configurations), the [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) bridge can wrap the hosted endpoint as a stdio command:
+
+```json
+{
+  "mcpServers": {
+    "moonbanking": {
+      "command": "npx",
+      "args": ["-y", "mcp-remote", "https://mcp.moonbanking.com/mcp"]
+    }
+  }
+}
+```
+
+## Self-hosted (API key)
+
+If you prefer to run the MCP server locally as a stdio process — for example to embed it in an automation that doesn't have a browser available for OAuth — install this npm package and authenticate with a Moon Banking API key.
 
 ### Direct invocation
 
@@ -34,22 +98,6 @@ For clients with a configuration JSON, it might look something like this:
 }
 ```
 
-### Cursor
-
-If you use Cursor, you can install the MCP server by using the button below. You will need to set your environment variables
-in Cursor's `mcp.json`, which can be found in Cursor Settings > Tools & MCP > New MCP Server.
-
-[![Add to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en-US/install-mcp?name=moonbanking-mcp&config=eyJlbnYiOnsiTU9PTl9CQU5LSU5HX0FQSV9LRVkiOiJTZXQgeW91ciBNT09OX0JBTktJTkdfQVBJX0tFWSBoZXJlLiJ9LCJjb21tYW5kIjoibnB4IC15IEBtb29uYmFua2luZy9tY3Atc2VydmVyIn0%3D)
-
-### Claude Code
-
-If you use Claude Code, you can install the MCP server by running the command below in your terminal. You will need to set your
-environment variables in Claude Code's `.claude.json`, which can be found in your home directory.
-
-```
-claude mcp add --transport stdio moonbanking_api --env MOON_BANKING_API_KEY="Your MOON_BANKING_API_KEY here." -- npx -y @moonbanking/mcp-server
-```
-
 ## Filter Specific Tools
 
 You can limit which tools are exposed by using the `--tool` flag:
@@ -70,7 +118,11 @@ npx @moonbanking/mcp-server --tool=tool1 --tool=tool2
 - `story_get`: This endpoint allows you to retrieve a paginated list of all stories. By default, a maximum of ten stories are shown per page. You can search stories by text content, filter by bank ID, sort them by various fields, and include related data like bank and country information.
 - `story_getById`: This endpoint allows you to retrieve a specific story by providing the story ID. You can include related data like bank and country information in the response.
 - `world_getOverview`: This endpoint allows you to retrieve global overview data that aggregates banks votes, stories and other data across all banks in all countries. You can include related data like scores in the response.
-- `search_get`: Search across banks, countries, and stories. You can specify which entities to search using the include parameter. If no include value is provided, all entities will be searched.
+- `market_get`: This endpoint allows you to retrieve a paginated list of markets (e.g. stock exchanges). You can search by name or code, filter by exact code, country, or market type, and sort the results.
+- `market_getById`: This endpoint allows you to retrieve a specific market (e.g. stock exchange) by providing the market id.
+- `stock_get`: This endpoint allows you to retrieve a paginated list of stock listings. You can search by ticker symbol, filter by exact symbol, market, bank, or primary-listing status, and sort the results.
+- `stock_getById`: This endpoint allows you to retrieve a specific stock listing by providing the stock id. You can optionally include the associated `market` and/or `bank` as nested objects.
+- `search_get`: Search across banks, countries, stories, and stocks. You can specify which entities to search using the include parameter. If no include value is provided, all entities will be searched. Banks are also matched on the ticker symbol of their stock listings, so searching `BAC` returns Bank of America.
 
 ## License
 

package/chatgpt.md

@@ -0,0 +1,87 @@
+# Moon Banking MCP for ChatGPT
+
+> Add the Moon Banking MCP server to ChatGPT via Custom Connectors or a Custom GPT.
+
+ChatGPT is great at fluent answers and weaker on fresh, structured facts about specific institutions. Adding the Moon Banking MCP as a Custom Connector gives ChatGPT live, tool-grounded access to every bank, country, community-rated score across 14 categories (customer service, fees & pricing, digital experience, crypto friendliness, security & trust, lending, transparency, and more), vote, and user story Moon Banking tracks.
+
+Use it for everything from *"which crypto-friendly banks operate in Argentina?"* to *"compare the top three US challenger banks on fees and digital experience"* to *"summarize what users are saying about Wells Fargo's customer service this year"* — and get citable, data-grounded answers instead of generic summaries.
+
+ChatGPT supports MCP through two distinct surfaces, and the right choice depends on your plan.
+
+## Recommended: hosted (OAuth) via Custom Connectors
+
+ChatGPT Plus, Pro, Team, Enterprise, and Edu users can add the Moon Banking server as a **Custom Connector** (the same mechanism that powers the official Notion, Gmail, etc. connectors).
+
+1. Open ChatGPT → **Settings → Connectors → Custom Connectors → Add custom connector**.
+2. Enter:
+   - **Name:** `Moon Banking`
+   - **URL:** `https://mcp.moonbanking.com/mcp`
+3. Save. ChatGPT will open a browser tab to authenticate with Moon Banking. Approve.
+4. In any chat, click the **+** button and enable the Moon Banking connector.
+
+> Custom Connectors require a paid plan with Connectors enabled for your region. Availability may vary; check [help.openai.com](https://help.openai.com) for current rollout status.
+
+## Alternative: stdio bridge for Custom GPTs / older setups
+
+If your plan doesn't expose Custom Connectors, you can wrap the hosted endpoint with [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) for any tooling that accepts stdio MCP (eg. a self-hosted ChatGPT-compatible agent):
+
+```json
+{
+  "mcpServers": {
+    "moonbanking": {
+      "command": "npx",
+      "args": ["-y", "mcp-remote", "https://mcp.moonbanking.com/mcp"]
+    }
+  }
+}
+```
+
+You can also run the stdio-only API-key package directly:
+
+```json
+{
+  "mcpServers": {
+    "moonbanking-mcp": {
+      "command": "npx",
+      "args": ["-y", "@moonbanking/mcp-server"],
+      "env": {
+        "MOON_BANKING_API_KEY": "Bearer mb_sk_..."
+      }
+    }
+  }
+}
+```
+
+## Verify the connection
+
+Start a new chat and prompt:
+
+> Use the Moon Banking connector to find banks in Singapore with strong fees and pricing scores.
+
+## Troubleshooting
+
+- **Connector option is missing.** Custom Connectors are gated by plan and region. Try the `mcp-remote` stdio bridge instead.
+- **OAuth returns to a 404.** Make sure your ChatGPT browser session is logged in and that pop-ups are allowed for chatgpt.com.
+
+
+## Available tools
+
+The Moon Banking MCP server exposes the following tools (identical across every client):
+
+- `bank_getByHostname`
+- `bank_get`
+- `bank_getById`
+- `bank_semanticSearch`
+- `bankVote_get`
+- `country_get`
+- `country_getByCountryCode`
+- `story_get`
+- `story_getById`
+- `world_getOverview`
+- `market_get`
+- `market_getById`
+- `stock_get`
+- `stock_getById`
+- `search_get`
+
+Full descriptions live on the [main MCP page](./README.md).

package/claude-code.md

@@ -0,0 +1,78 @@
+# Moon Banking MCP for Claude Code
+
+> Add the Moon Banking MCP server to the Claude Code CLI for use in terminal-driven coding sessions.
+
+Claude Code is the right tool when you're scripting against APIs, automating data work, or hacking on a fintech backend without leaving your terminal. Adding the Moon Banking MCP gives the CLI agent live access to the entire Moon Banking dataset — banks, countries, community-rated scores across 14 categories (customer service, fees & pricing, digital experience, crypto friendliness, lending, transparency, …), user votes, user stories, and global rankings — over either the hosted OAuth endpoint or a local stdio process.
+
+Typical uses: seeding a fintech database with realistic bank records, generating evaluation datasets that need real institutions, prototyping "find me a bank that…" features, or pausing mid-script to ask *"which US banks have the highest customer-service scores?"* without context-switching to a browser.
+
+Claude Code is Anthropic's terminal CLI. It supports both **remote** (HTTP/Streamable HTTP) and **stdio** MCP transports.
+
+## Recommended: hosted (OAuth)
+
+Run this once in any directory:
+
+```bash
+claude mcp add --transport http moonbanking https://mcp.moonbanking.com/mcp
+```
+
+The first time you invoke a Moon Banking tool, Claude Code will print a one-time URL and ask you to authenticate in your browser. The resulting OAuth token is cached on disk and reused across sessions.
+
+To install only for the current project (instead of globally), pass `--scope project`:
+
+```bash
+claude mcp add --transport http --scope project moonbanking https://mcp.moonbanking.com/mcp
+```
+
+The project-scoped config lives in `.claude.json` at the project root and can be committed to source control if you want every developer on the team to share it.
+
+## Alternative: self-hosted (API key)
+
+```bash
+claude mcp add --transport stdio moonbanking \
+  --env MOON_BANKING_API_KEY="Bearer mb_sk_..." \
+  -- npx -y @moonbanking/mcp-server
+```
+
+This launches a local stdio MCP server that authenticates with your API key on every call.
+
+## Verify the connection
+
+```bash
+claude mcp list
+```
+
+You should see `moonbanking` listed with a connection status of `connected`. Then start a session and try:
+
+```
+> Find the highest-rated bank in Switzerland for crypto users.
+```
+
+## Troubleshooting
+
+- **`Failed to authenticate`** Run `claude mcp remove moonbanking` and re-add to clear the cached token.
+- **No tools available.** Run `claude mcp list` — if the server appears with a red status, run `claude mcp logs moonbanking` to inspect the error.
+- **Pro plan required.** The MCP API rejects non-Pro Moon Banking accounts; [upgrade to Pro](https://moonbanking.com/pro).
+
+
+## Available tools
+
+The Moon Banking MCP server exposes the following tools (identical across every client):
+
+- `bank_getByHostname`
+- `bank_get`
+- `bank_getById`
+- `bank_semanticSearch`
+- `bankVote_get`
+- `country_get`
+- `country_getByCountryCode`
+- `story_get`
+- `story_getById`
+- `world_getOverview`
+- `market_get`
+- `market_getById`
+- `stock_get`
+- `stock_getById`
+- `search_get`
+
+Full descriptions live on the [main MCP page](./README.md).

package/claude.md

@@ -0,0 +1,99 @@
+# Moon Banking MCP for Claude
+
+> Add the Moon Banking MCP server to Claude Desktop and claude.ai as a custom connector.
+
+Claude is one of the strongest models for nuanced research and writing, and one of its biggest weak points is fresh, structured data about specific institutions. The Moon Banking MCP gives Claude live access to every bank, country, community-rated score across 14 categories (customer service, fees & pricing, digital experience, crypto friendliness, security & trust, lending, transparency, and more), vote, and user story in the Moon Banking database — so questions about real-world banks come back with citable, tool-grounded facts instead of generic training-data summaries.
+
+Try *"draft a comparison of the three highest-rated digital banks in Germany, then tell me which has the best reviews on fees"*, *"summarize what users are saying about HSBC's customer service this year"*, or *"which banks in Brazil rank highest on crypto friendliness?"* — Claude will pull the data on demand and reason over it in-line.
+
+Claude Desktop and claude.ai both support remote MCP servers as **custom connectors**. The hosted Moon Banking endpoint uses Streamable HTTP with OAuth, which both clients handle out of the box.
+
+## Recommended: hosted (OAuth)
+
+### Claude Desktop
+
+1. Open **Settings → Connectors** (or **Settings → Developer → Add custom connector**, depending on your version).
+2. Choose **Add custom connector**.
+3. Set:
+   - **Name:** `Moon Banking`
+   - **URL:** `https://mcp.moonbanking.com/mcp`
+4. Click **Add**. Claude will open a browser window asking you to sign in to Moon Banking. Approve the connection.
+5. Back in Claude, toggle the **Moon Banking** connector on in any chat.
+
+If you prefer to edit the config file directly, on macOS it lives at `~/Library/Application Support/Claude/claude_desktop_config.json`. On Windows it's `%APPDATA%\Claude\claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "moonbanking": {
+      "url": "https://mcp.moonbanking.com/mcp"
+    }
+  }
+}
+```
+
+Restart Claude Desktop after editing.
+
+### claude.ai (web)
+
+1. Sign in at [claude.ai](https://claude.ai) on a Pro, Team, or Enterprise plan (custom connectors require a paid plan).
+2. Go to **Settings → Connectors → Add custom connector**.
+3. Paste `https://mcp.moonbanking.com/mcp` and confirm.
+4. Approve the OAuth prompt that opens.
+
+## Alternative: self-hosted (API key)
+
+If you need a stdio connection (eg. air-gapped use or a service account), Claude Desktop can spawn the published npm package locally. Add this to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "moonbanking-mcp": {
+      "command": "npx",
+      "args": ["-y", "@moonbanking/mcp-server"],
+      "env": {
+        "MOON_BANKING_API_KEY": "Bearer mb_sk_..."
+      }
+    }
+  }
+}
+```
+
+Generate the API key at [moonbanking.com/settings/api/manage-api-keys](https://moonbanking.com/settings/api/manage-api-keys) and restart Claude.
+
+## Verify the connection
+
+Start a new conversation in Claude and ask:
+
+> Using the Moon Banking connector, find banks in Brazil that are known for being crypto-friendly.
+
+Claude should call tools like `bank_semanticSearch` or `country_getByCountryCode` and reply with real Moon Banking data.
+
+## Troubleshooting
+
+- **Connector shows as disconnected.** Click the connector in Settings and re-run the auth flow. If your access token expired Claude will need to re-authenticate.
+- **`Tool list is empty`** Make sure your account has been granted Pro access at moonbanking.com. The MCP endpoint requires a Pro subscription.
+- **Cannot add connector.** Claude.ai's custom connectors are gated to paid plans. Claude Desktop has fewer restrictions.
+
+
+## Available tools
+
+The Moon Banking MCP server exposes the following tools (identical across every client):
+
+- `bank_getByHostname`
+- `bank_get`
+- `bank_getById`
+- `bank_semanticSearch`
+- `bankVote_get`
+- `country_get`
+- `country_getByCountryCode`
+- `story_get`
+- `story_getById`
+- `world_getOverview`
+- `market_get`
+- `market_getById`
+- `stock_get`
+- `stock_getById`
+- `search_get`
+
+Full descriptions live on the [main MCP page](./README.md).

package/cursor.md

@@ -0,0 +1,90 @@
+# Moon Banking MCP for Cursor
+
+> Connect Cursor to the Moon Banking MCP server so the AI can query banks, countries, votes, and stories with one-click OAuth.
+
+Cursor's agent is excellent at writing code but has no built-in knowledge of specific banks, their hostnames, fee structures, or how real customers rate them. Wiring in the Moon Banking MCP closes that gap: Cursor gains live access to every bank Moon Banking tracks — name, country, primary hostname, rank, community-rated scores across 14 categories (customer service, fees & pricing, digital experience, crypto friendliness, security & trust, lending, and more) — plus the user-submitted stories backing those scores.
+
+Useful when you're scaffolding a fintech project, validating bank hostnames you see in code, generating realistic test fixtures, or just prompting *"find me a crypto-friendly business bank in Singapore and stub out a client for its public API"* mid-session. Answers are grounded in fresh Moon Banking data — not whatever your model memorized last year.
+
+Cursor speaks remote MCP natively over Streamable HTTP. The fastest setup is to point Cursor at the hosted endpoint — Cursor handles the OAuth flow in a browser tab automatically.
+
+## Recommended: hosted (OAuth)
+
+### Option A — Click to install
+
+[![Add to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](cursor://anysphere.cursor-deeplink/mcp/install?name=moonbanking&config=eyJ1cmwiOiJodHRwczovL21jcC5tb29uYmFua2luZy5jb20vbWNwIn0%3D)
+
+### Option B — Edit `mcp.json` directly
+
+Open Cursor and go to **Settings → Tools & MCP → New MCP Server**, or edit your global config at `~/.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "moonbanking": {
+      "url": "https://mcp.moonbanking.com/mcp"
+    }
+  }
+}
+```
+
+For project-scoped install instead, drop the same JSON at `.cursor/mcp.json` inside your repository.
+
+The first time Cursor connects, it will open a browser window asking you to sign in to Moon Banking. After that, the connection persists across restarts.
+
+## Alternative: self-hosted (API key)
+
+If you would rather run the MCP server locally as a stdio process (eg. you are on a machine without a browser, or you want to use a service API key), Cursor can spawn the published npm package.
+
+```json
+{
+  "mcpServers": {
+    "moonbanking-mcp": {
+      "command": "npx",
+      "args": ["-y", "@moonbanking/mcp-server"],
+      "env": {
+        "MOON_BANKING_API_KEY": "Bearer mb_sk_..."
+      }
+    }
+  }
+}
+```
+
+Generate an API key at [moonbanking.com/settings/api/manage-api-keys](https://moonbanking.com/settings/api/manage-api-keys).
+
+## Verify the connection
+
+Open the Cursor chat panel and look for the **MCP** indicator beside the model picker — it should show `moonbanking` with a green dot and the tool count. You can also ask the agent something like:
+
+> What are the top three banks in Germany right now?
+
+If it responds using the `bank_get` and `country_get` tools, the connection is working.
+
+## Troubleshooting
+
+- **Tools list is empty.** Cursor may have cached an unauthenticated session. Remove the entry from `mcp.json`, restart Cursor, and re-add it. If the issue persists, run `npx @modelcontextprotocol/inspector` against `https://mcp.moonbanking.com/mcp` to confirm the server is reachable from your network.
+- **OAuth window closes immediately.** Make sure your default browser is signed in to Moon Banking, or sign in first at [moonbanking.com](https://moonbanking.com) and retry.
+- **403 errors after sign-in.** Your Moon Banking account must be on a Pro plan to use the MCP API. [Upgrade to Pro](https://moonbanking.com/pro).
+
+
+## Available tools
+
+The Moon Banking MCP server exposes the following tools (identical across every client):
+
+- `bank_getByHostname`
+- `bank_get`
+- `bank_getById`
+- `bank_semanticSearch`
+- `bankVote_get`
+- `country_get`
+- `country_getByCountryCode`
+- `story_get`
+- `story_getById`
+- `world_getOverview`
+- `market_get`
+- `market_getById`
+- `stock_get`
+- `stock_getById`
+- `search_get`
+
+Full descriptions live on the [main MCP page](./README.md).