Skip to main content
Glama
USCardForum MCP Server

USCardForum MCP Server

by hmumixaM

USCardForum MCP Server

A production-ready Model Context Protocol (MCP) server for interacting with USCardForum, a Discourse-based community focused on US credit cards, points, miles, and financial optimization.

Features

  • 22 Tools organized into 4 logical groups:

    • šŸ“° Discovery (5) — Find topics via hot/new/top/search/categories

    • šŸ“– Reading (3) — Access topic content with pagination

    • šŸ‘¤ Users (9) — Profile research, badges, activity, social

    • šŸ” Auth (5) — Login, notifications, bookmarks, subscriptions

  • 4 Prompts for guided research workflows (Chinese)

  • 3 Resources for quick data access

  • Multiple Transports — stdio, SSE, Streamable HTTP

  • Strongly Typed with Pydantic domain models

  • Rate Limiting with exponential backoff

  • Cloudflare Bypass via cloudscraper

  • Heroku Ready deployment configuration

Related MCP server: USCardForum MCP Server

Project Structure

uscardforum/
ā”œā”€ā”€ src/uscardforum/
│   ā”œā”€ā”€ __init__.py          # Package exports
│   ā”œā”€ā”€ client.py            # Main client (composes APIs)
│   ā”œā”€ā”€ server.py            # FastMCP server (MCP layer)
│   ā”œā”€ā”€ server_core.py       # Server configuration
│   ā”œā”€ā”€ models/              # Domain models (Pydantic)
│   │   ā”œā”€ā”€ topics.py        # Topic, Post, TopicInfo, TopicSummary
│   │   ā”œā”€ā”€ users.py         # UserSummary, UserAction, Badge, etc.
│   │   ā”œā”€ā”€ search.py        # SearchResult, SearchPost, SearchTopic
│   │   ā”œā”€ā”€ categories.py    # Category, CategoryMap
│   │   └── auth.py          # Session, Notification, Bookmark, etc.
│   ā”œā”€ā”€ api/                 # API modules (backend)
│   │   ā”œā”€ā”€ base.py          # Base API with HTTP methods
│   │   ā”œā”€ā”€ topics.py        # Topic operations
│   │   ā”œā”€ā”€ users.py         # User profile operations
│   │   ā”œā”€ā”€ search.py        # Search operations
│   │   └── auth.py          # Authentication operations
│   ā”œā”€ā”€ server_tools/        # MCP tool definitions
│   └── utils/               # HTTP and Cloudflare utilities
ā”œā”€ā”€ tests/                   # Integration tests
ā”œā”€ā”€ .github/workflows/       # CI/CD workflows
│   ā”œā”€ā”€ ci.yml               # Tests, linting, type checking
│   └── deploy.yml           # Multi-platform deployment
ā”œā”€ā”€ Dockerfile               # Container build
ā”œā”€ā”€ docker-compose.yml       # Local development
ā”œā”€ā”€ fly.toml                 # Fly.io configuration
ā”œā”€ā”€ railway.toml             # Railway configuration
ā”œā”€ā”€ render.yaml              # Render blueprint
ā”œā”€ā”€ koyeb.yaml               # Koyeb configuration
ā”œā”€ā”€ digitalocean-app.yaml    # DigitalOcean App Platform
ā”œā”€ā”€ cloudbuild.yaml          # Google Cloud Build
ā”œā”€ā”€ heroku.yml               # Heroku manifest
ā”œā”€ā”€ app.json                 # Heroku button config
ā”œā”€ā”€ Procfile                 # Heroku process
└── pyproject.toml           # Python package config

Installation

# Clone the repository
git clone https://github.com/uscardforum/mcp-server.git
cd uscardforum

# Install with UV
uv sync

# Run the server
uv run uscardforum

Using pip

# Clone the repository
git clone https://github.com/uscardforum/mcp-server.git
cd uscardforum

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # or .venv\Scripts\activate on Windows

# Install
pip install -e .

# Run
uscardforum

Configuration

Environment Variables

Variable

Default

Description

MCP_TRANSPORT

stdio

Transport mode: stdio, sse, or streamable-http

MCP_HOST

0.0.0.0

HTTP server host (for sse/streamable-http)

MCP_PORT

8000

HTTP server port (for sse/streamable-http)

NITAN_TOKEN

(none)

Bearer token for MCP auth (streamable-http only)

USCARDFORUM_URL

https://www.uscardforum.com

Forum base URL

USCARDFORUM_TIMEOUT

15.0

Request timeout in seconds

NITAN_USERNAME

(none)

Auto-login username (optional)

NITAN_PASSWORD

(none)

Auto-login password (optional)

Transport Modes

The server supports three transport modes:

  • stdio (default): Standard input/output, used by Cursor and Claude Desktop

  • sse: Server-Sent Events over HTTP

  • streamable-http: Streamable HTTP transport (recommended for web deployments)

Running with Streamable HTTP

# Start server with streamable HTTP transport
MCP_TRANSPORT=streamable-http MCP_PORT=8000 uv run uscardforum

# The MCP endpoint will be available at:
# http://localhost:8000/mcp

Streamable HTTP Authentication

When using streamable-http transport, you can require clients to authenticate with a bearer token by setting NITAN_TOKEN:

# Start server with authentication required
MCP_TRANSPORT=streamable-http NITAN_TOKEN=my-secret-token uv run uscardforum

# Clients must include Authorization header:
# Authorization: Bearer my-secret-token

This is useful for securing public deployments. The token is only enforced for streamable-http transport; stdio and sse modes do not use this authentication.

Forum Auto-Login

If both NITAN_USERNAME and NITAN_PASSWORD are set, the server automatically logs into the forum on startup. This enables authenticated features (notifications, bookmarks, subscriptions) without manual login.

Cursor IDE Integration

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "uscardforum": {
      "command": "uv",
      "args": ["--directory", "/path/to/uscardforum", "run", "uscardforum"],
      "env": {
        "NITAN_USERNAME": "your_forum_username",
        "NITAN_PASSWORD": "your_forum_password"
      }
    }
  }
}

Claude Desktop Integration

Add to Claude Desktop's config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "uscardforum": {
      "command": "uv",
      "args": ["--directory", "/path/to/uscardforum", "run", "uscardforum"],
      "env": {
        "NITAN_USERNAME": "your_forum_username",
        "NITAN_PASSWORD": "your_forum_password"
      }
    }
  }
}

Deployment

The USCardForum MCP Server supports multiple deployment platforms. Choose the one that best fits your needs.

Quick Comparison

Platform

Starting Price

Pros

Best For

Heroku

$7/mo

Easy, one-click deploy

Quick start

Railway

$5/mo

Simple, GitHub integration

Developers

Render

$7/mo

Auto-scaling, free tier

Production

Fly.io

$0-5/mo

Edge deployment, generous free tier

Global reach

Google Cloud Run

Pay-per-use

Auto-scaling to zero

Variable traffic

DigitalOcean

$5/mo

Predictable pricing

Self-managed

Koyeb

$5/mo

Fast deploys, global edge

Low latency

Cloudflare

Free

Global edge network

Edge deployment

Docker

Self-hosted

Full control

Privacy-conscious


Heroku

Deploy

# Manual deployment
heroku login
heroku create your-app-name

# Set environment variables
heroku config:set NITAN_TOKEN=$(openssl rand -hex 32)
heroku config:set NITAN_USERNAME=your_username
heroku config:set NITAN_PASSWORD=your_password

# Deploy
git push heroku main
heroku ps:scale web=1

Railway

Deploy on Railway

# Install Railway CLI
npm i -g @railway/cli

# Login and deploy
railway login
railway init
railway up

# Set environment variables
railway variables set MCP_TRANSPORT=streamable-http
railway variables set NITAN_TOKEN=$(openssl rand -hex 32)
railway variables set NITAN_USERNAME=your_username
railway variables set NITAN_PASSWORD=your_password

# Open dashboard
railway open

Render

Deploy to Render

  1. Connect your GitHub repository to Render

  2. Create a new Web Service

  3. Select Docker as the runtime

  4. Set environment variables in the dashboard:

    • MCP_TRANSPORT=streamable-http

    • NITAN_TOKEN=your-secret-token

    • NITAN_USERNAME=your-username (optional)

    • NITAN_PASSWORD=your-password (optional)

Or use the blueprint file:

# render.yaml is included in the repository
# Just connect your repo and Render will auto-detect it

Fly.io

# Install Fly CLI
curl -L https://fly.io/install.sh | sh

# Login and launch
fly auth login
fly launch --name uscardforum-mcp

# Set secrets
fly secrets set NITAN_TOKEN=$(openssl rand -hex 32)
fly secrets set NITAN_USERNAME=your_username
fly secrets set NITAN_PASSWORD=your_password

# Deploy
fly deploy

# Check status
fly status
fly logs

Google Cloud Run

Open in Cloud Shell

After clicking, run in Cloud Shell:

# Deploy to Cloud Run
gcloud run deploy uscardforum-mcp \
  --source . \
  --region us-west1 \
  --platform managed \
  --allow-unauthenticated \
  --port 8000 \
  --memory 512Mi \
  --set-env-vars "MCP_TRANSPORT=streamable-http,MCP_HOST=0.0.0.0,MCP_PORT=8000"

Or deploy via CLI:

# Enable required APIs
gcloud services enable run.googleapis.com cloudbuild.googleapis.com

# Deploy directly from source
gcloud run deploy uscardforum-mcp \
  --source . \
  --region us-west1 \
  --platform managed \
  --allow-unauthenticated \
  --port 8000 \
  --memory 512Mi \
  --set-env-vars "MCP_TRANSPORT=streamable-http,MCP_HOST=0.0.0.0,MCP_PORT=8000"

# Set secrets (create them first in Secret Manager)
gcloud run services update uscardforum-mcp \
  --set-secrets="NITAN_TOKEN=nitan-token:latest"

Or use Cloud Build with the included cloudbuild.yaml:

gcloud builds submit --config cloudbuild.yaml

DigitalOcean App Platform

# Install doctl CLI
brew install doctl  # or: snap install doctl

# Authenticate
doctl auth init

# Create app from spec
doctl apps create --spec digitalocean-app.yaml

# Or deploy via dashboard:
# 1. Go to https://cloud.digitalocean.com/apps
# 2. Create App → GitHub → Select repository
# 3. Configure environment variables

Koyeb

# Install Koyeb CLI
curl -fsSL https://raw.githubusercontent.com/koyeb/koyeb-cli/master/install.sh | sh

# Login and deploy
koyeb login
koyeb app create uscardforum-mcp \
  --docker-image ghcr.io/uscardforum/mcp-server:latest \
  --ports 8000:http \
  --env MCP_TRANSPORT=streamable-http \
  --env MCP_PORT=8000

# Set secrets
koyeb secrets create nitan-token --value your-secret-token
koyeb app update uscardforum-mcp --env NITAN_TOKEN=@nitan-token

Cloudflare Containers

Deploy to Cloudflare


Docker (Self-Hosted)

# Pull from Docker Hub (recommended)
docker pull uscarddev/uscardforum-mcp:latest

# Run the container
docker run -d \
  -p 8000:8000 \
  -e MCP_TRANSPORT=streamable-http \
  -e NITAN_TOKEN=your-secret-token \
  --name uscardforum-mcp \
  uscarddev/uscardforum-mcp:latest

# Or build locally
docker build -t uscardforum-mcp .
docker run -d \
  -p 8000:8000 \
  -e MCP_TRANSPORT=streamable-http \
  -e NITAN_TOKEN=your-secret-token \
  --name uscardforum-mcp \
  uscardforum-mcp

# Or use Docker Compose
docker compose up -d

# View logs
docker compose logs -f

Docker Hub: uscarddev/uscardforum-mcp

Available tags:

  • latest - Latest stable release

  • tagname - Specific version tags

For production with HTTPS, use a reverse proxy like Traefik or nginx. See docker-compose.yml for Traefik example.


Environment Variables Reference

Variable

Default

Required

Description

MCP_TRANSPORT

stdio

āœ“

Set to streamable-http for web deployment

MCP_HOST

0.0.0.0

HTTP server bind address

MCP_PORT

8000

HTTP server port (some platforms override this)

NITAN_TOKEN

Bearer token for MCP authentication

USCARDFORUM_URL

https://www.uscardforum.com

Forum base URL

USCARDFORUM_TIMEOUT

15.0

Request timeout in seconds

NITAN_USERNAME

Forum auto-login username

NITAN_PASSWORD

Forum auto-login password


Connecting to Your Deployed Server

After deployment, connect from Cursor or other MCP clients using the streamable HTTP URL:

{
  "mcpServers": {
    "uscardforum": {
      "url": "https://your-app.fly.dev/mcp",
      "headers": {
        "Authorization": "Bearer your-nitan-token"
      }
    }
  }
}

Replace the URL with your deployment's URL:

  • Heroku: https://your-app.herokuapp.com/mcp

  • Railway: https://your-app.up.railway.app/mcp

  • Render: https://your-app.onrender.com/mcp

  • Fly.io: https://your-app.fly.dev/mcp

  • Cloud Run: https://your-app-xxxxx-uc.a.run.app/mcp

  • DigitalOcean: https://your-app.ondigitalocean.app/mcp

  • Koyeb: https://your-app.koyeb.app/mcp

Testing

Run integration tests against the live forum:

# Set test credentials
export NITAN_USERNAME="your_test_username"
export NITAN_PASSWORD="your_test_password"

# Run tests
uv run pytest tests/ -v

# Run with coverage
uv run pytest tests/ --cov=uscardforum --cov-report=term-missing

Domain Models

All return types are strongly typed with Pydantic models:

Topic Models

from uscardforum import TopicSummary, TopicInfo, Post

# TopicSummary - for list views
topic: TopicSummary
topic.id          # int: Topic ID
topic.title       # str: Topic title
topic.posts_count # int: Number of posts
topic.views       # int: View count
topic.like_count  # int: Total likes

# TopicInfo - detailed metadata
info: TopicInfo
info.post_count          # int: Total posts
info.highest_post_number # int: Last post number

# Post - individual post
post: Post
post.id           # int: Post ID
post.post_number  # int: Position in topic
post.username     # str: Author
post.cooked       # str: HTML content
post.like_count   # int: Likes

User Models

from uscardforum import UserSummary, UserAction, Badge

# UserSummary - profile overview
summary: UserSummary
summary.username  # str: Username
summary.stats     # UserStats: Activity statistics
summary.badges    # List[Badge]: Earned badges

# UserAction - activity entry
action: UserAction
action.topic_id   # int: Related topic
action.excerpt    # str: Content preview

Search Models

from uscardforum import SearchResult, SearchPost, SearchTopic

# SearchResult - search response
result: SearchResult
result.posts   # List[SearchPost]: Matching posts
result.topics  # List[SearchTopic]: Matching topics
result.users   # List[SearchUser]: Matching users

Auth Models

from uscardforum import LoginResult, Session, Notification, Bookmark

# LoginResult - login response
login: LoginResult
login.success      # bool: Whether succeeded
login.requires_2fa # bool: 2FA needed

# Session - current session
session: Session
session.is_authenticated  # bool: Logged in
session.current_user      # CurrentUser: User info

API Modules

The backend is split into focused API modules:

Module

Purpose

TopicsAPI

Topic lists, posts, pagination

UsersAPI

Profiles, activity, badges, social

SearchAPI

Full-text search

CategoriesAPI

Category mappings

AuthAPI

Login, notifications, bookmarks

Each module inherits from BaseAPI which provides rate-limited HTTP methods.

Available Tools (22 Tools)

šŸ“° Discovery — Find Content to Read

Tool

Return Type

Description

get_hot_topics

List[TopicSummary]

Currently trending topics by engagement

get_new_topics

List[TopicSummary]

Latest topics by creation time

get_top_topics

List[TopicSummary]

Top topics by period (daily/weekly/monthly/yearly)

search_forum

SearchResult

Full-text search with operators

get_categories

CategoryMap

Category ID to name mapping

šŸ“– Reading — Access Topic Content

Tool

Return Type

Description

get_topic_info

TopicInfo

Topic metadata (check post count first!)

get_topic_posts

List[Post]

Fetch ~20 posts starting at position

get_all_topic_posts

List[Post]

Fetch all posts with auto-pagination

šŸ‘¤ Users — Profile & Activity Research

Tool

Return Type

Description

get_user_summary

UserSummary

Profile overview and stats

get_user_topics

List[Dict]

Topics created by user

get_user_replies

List[UserAction]

User's reply history

get_user_actions

List[UserAction]

Full activity feed

get_user_badges

UserBadges

Badges earned by user

get_user_following

FollowList

Who the user follows

get_user_followers

FollowList

Who follows the user

get_user_reactions

UserReactions

Reactions given/received

list_users_with_badge

Dict

Find users with specific badge

šŸ” Auth — Authenticated Actions (requires login)

Tool

Return Type

Description

login

LoginResult

Authenticate with forum credentials

get_current_session

Session

Check authentication status

get_notifications

List[Notification]

Fetch user notifications

bookmark_post

Bookmark

Bookmark a post for later

subscribe_topic

SubscriptionResult

Set topic notification level

Available Prompts (4 Prompts, äø­ę–‡)

Guided workflows for common research tasks:

Prompt

Args

Purpose

research_topic

topic_query

ē ”ē©¶č®ŗå›ē‰¹å®šäø»é¢˜ļ¼Œę€»ē»“ē¤¾åŒŗå…±čÆ†

analyze_user

username

åˆ†ęžē”Øęˆ·čµ„ę–™ć€č“”ēŒ®å’ŒåÆäæ”åŗ¦

find_data_points

subject

ęŸ„ę‰¾ē”Øęˆ·ęŠ„å‘Šēš„ēœŸå®žę•°ę®ē‚¹

compare_cards

card1, card2

ęÆ”č¾ƒäø¤å¼ äæ”ē”Øå”ēš„ē¤¾åŒŗč®Øč®ŗ

Available Resources (3 Resources)

Quick-access static data:

URI

Description

forum://categories

Category ID → name mapping (JSON)

forum://hot-topics

Top 20 trending topics (JSON)

forum://new-topics

Top 20 latest topics (JSON)

Usage Examples

Using the Client Directly

from uscardforum import DiscourseClient

client = DiscourseClient()

# Browse hot topics
for topic in client.get_hot_topics():
    print(f"{topic.title} ({topic.posts_count} posts, {topic.views} views)")

# Get topic info and posts
info = client.get_topic_info(12345)
print(f"Topic has {info.post_count} posts")

posts = client.get_topic_posts(12345)
for post in posts:
    print(f"#{post.post_number} by {post.username}: {post.like_count} likes")

# Search
results = client.search("Chase Sapphire Reserve", order="latest")
for post in results.posts:
    print(f"[Topic {post.topic_id}] {post.blurb}")

# User profile
summary = client.get_user_summary("creditexpert")
print(f"{summary.username}: {summary.stats.post_count} posts")

Forum Authentication

# Login to forum
result = client.login("username", "password")
if result.success:
    print(f"Logged in as {result.username}")
elif result.requires_2fa:
    result = client.login("username", "password", second_factor_token="123456")

# Get notifications
notifications = client.get_notifications(only_unread=True)
for n in notifications:
    print(f"Notification {n.id}: {n.notification_type}")

# Bookmark a post
bookmark = client.bookmark_post(54321, name="Important info")

Architecture

Separation of Concerns

  1. Domain Models (models/)

    • Pydantic models for all return types

    • Strong typing and validation

    • Clear documentation

  2. API Modules (api/)

    • Focused functionality per domain

    • Inherits from BaseAPI for HTTP

    • Returns domain models

  3. Client (client.py)

    • Composes all API modules

    • Unified interface

    • Session management

  4. MCP Server (server.py)

    • FastMCP tool definitions

    • Bearer token authentication

    • Extensive docstrings (Chinese)

    • Prompts and resources

Security

  • MCP Authentication: Bearer token via HTTP Authorization header (MCP transport-level)

  • Rate Limiting: 4 requests per second with exponential backoff

  • Cloudflare Bypass: Automatic handling via cloudscraper

Development

# Install dev dependencies
uv sync --group dev

# Run tests
NITAN_USERNAME="user" NITAN_PASSWORD="pass" uv run pytest

# Lint
uv run ruff check src/

# Type check
uv run mypy src/

License

MIT

Contributing

Contributions welcome! Please:

  1. Fork the repository

  2. Create a feature branch

  3. Submit a pull request

Acknowledgments

Available Tools

22 tools
bookmark_postA
Bookmark a post for later reference. REQUIRES AUTHENTICATION.

Args:
    post_id: The numeric post ID to bookmark
    name: Optional label/name for the bookmark
    reminder_type: Optional reminder setting
    reminder_at: Optional reminder datetime (ISO format)
    auto_delete_preference: When to auto-delete (default: 3)
        - 0: Never
        - 1: When reminder sent
        - 2: On click
        - 3: Clear after 3 days

Must call login() first.

Returns a Bookmark object with the created bookmark information.

Use to save interesting posts for later reference.

Inputs: post_id (required), name, reminder_type, reminder_at, +1 more. Returns: A bookmarked post.

get_all_topic_postsA
Fetch all posts from a topic with automatic pagination.

Args:
    topic_id: The numeric topic ID
    include_raw: Include markdown source (default: False)
    start_post_number: First post to fetch (default: 1)
    end_post_number: Last post to fetch (optional, fetches to end if not set)
    max_posts: Maximum number of posts to return (optional safety limit)

This automatically handles pagination to fetch multiple batches.

IMPORTANT: For topics with many posts (>100), use max_posts to limit
the response size. You can always fetch more with start_post_number.

Use cases:
- Fetch entire small topic: get_all_topic_posts(topic_id=123)
- Fetch first 50 posts: get_all_topic_posts(topic_id=123, max_posts=50)
- Fetch posts 51-100: get_all_topic_posts(topic_id=123, start_post_number=51, max_posts=50)
- Fetch specific range: get_all_topic_posts(topic_id=123, start=10, end=30)

Returns the same Post structure as get_topic_posts but for all matching posts.

Pro tip: Use get_topic_info first to check post_count before deciding
whether to fetch all or paginate manually.

Inputs: topic_id (required), include_raw, start_post_number, end_post_number, +1 more. Returns: result

get_categoriesA
Get a mapping of all forum categories.

Returns a CategoryMap object with category_id to category name mapping.
Categories organize topics by subject area.

Common USCardForum categories include sections for:
- Credit card applications and approvals
- Bank account bonuses
- Travel and redemptions
- Data points and experiences

Use category IDs to:
- Filter search results by category
- Understand which section a topic belongs to
- Navigate to specific areas of interest

The mapping includes both main categories and subcategories.

Inputs: no named parameters. Returns: Mapping of category IDs to names.

get_current_sessionA
Get information about the current session.

Returns a Session object with:
- is_authenticated: Whether logged in
- current_user: CurrentUser object with user info (if authenticated)

Use to verify authentication status.

Inputs: no named parameters. Returns: Current session information.

get_hot_topicsA
Fetch currently trending/hot topics from USCardForum.

This returns the most actively discussed topics right now, ranked by
engagement metrics like recent replies, views, and likes.

Use this to:
- See what the community is currently discussing
- Find breaking news or time-sensitive opportunities
- Discover popular ongoing discussions

Args:
    page: Page number for pagination (0-indexed). Use page=1 to get more topics.

Returns a list of TopicSummary objects with fields:
- id: Topic ID (use with get_topic_posts)
- title: Topic title
- posts_count: Total replies
- views: View count
- like_count: Total likes
- created_at: Creation timestamp
- last_posted_at: Last activity timestamp

Example response interpretation:
A topic with high views but low posts may be informational.
A topic with many recent posts is actively being discussed.

Inputs: page. Returns: result

get_new_topicsA
Fetch the latest/newest topics from USCardForum.

Returns recently created topics sorted by creation time (newest first).
These may have fewer replies but contain fresh information.

Use this to:
- Find newly posted deals or offers
- See fresh questions from the community
- Discover emerging discussions before they get popular

Args:
    page: Page number for pagination (0-indexed). Use page=1 to get more topics.

Returns a list of TopicSummary objects with:
- id: Topic ID
- title: Topic title
- posts_count: Number of posts
- created_at: When the topic was created
- category_id: Which forum section it's in

Tip: New topics with high view counts may indicate important news.

Inputs: page. Returns: result

get_notificationsA
Fetch your notifications. REQUIRES AUTHENTICATION.

Args:
    since_id: Only get notifications newer than this ID (optional)
    only_unread: Only return unread notifications (default: False)
    limit: Maximum number to return (optional)

Must call login() first.

Returns a list of Notification objects with:
- id: Notification ID
- notification_type: Type of notification
- read: Whether read
- topic_id: Related topic
- post_number: Related post
- created_at: When created

Use to:
- Check for new replies to your posts
- See mentions and likes
- Track topic updates you're watching

Inputs: since_id, only_unread, limit. Returns: result

get_topic_infoA
Get metadata about a specific topic without fetching all posts.

Args:
    topic_id: The numeric topic ID (from URLs like /t/slug/12345)

Use this FIRST before reading a topic to:
- Check how many posts it contains (for pagination planning)
- Get the topic title and timestamps
- Decide whether to fetch all posts or paginate

Returns a TopicInfo object with:
- topic_id: The topic ID
- title: Full topic title
- post_count: Total number of posts
- highest_post_number: Last post number (may differ from count if posts deleted)
- last_posted_at: When the last reply was made

Strategy for large topics:
- <50 posts: Safe to fetch all at once
- 50-200 posts: Consider using max_posts parameter
- >200 posts: Fetch in batches or summarize key posts

Inputs: topic_id (required). Returns: Detailed topic metadata.

get_topic_postsA
Fetch a batch of posts from a topic starting at a specific position.

Args:
    topic_id: The numeric topic ID
    post_number: Which post number to start from (default: 1 = first post)
    include_raw: Include raw markdown source (default: False, returns HTML)

This fetches ~20 posts per call starting from post_number.
Use for paginated reading of topics.

Returns a list of Post objects with:
- post_number: Position in topic (1, 2, 3...)
- username: Author's username
- cooked: HTML content of the post
- raw: Markdown source (if include_raw=True)
- created_at: When posted
- updated_at: Last edit time
- like_count: Number of likes
- reply_count: Number of direct replies
- reply_to_post_number: Which post this replies to (if any)

Pagination example:
1. Call with post_number=1, get posts 1-20
2. Call with post_number=21, get posts 21-40
3. Continue until no posts returned

Inputs: topic_id (required), post_number, include_raw. Returns: result

get_top_topicsA
Fetch top-performing topics for a specific time period.

Args:
    period: Time window for ranking. Must be one of:
        - "daily": Top topics from today
        - "weekly": Top topics this week
        - "monthly": Top topics this month (default)
        - "quarterly": Top topics this quarter
        - "yearly": Top topics this year
    page: Page number for pagination (0-indexed). Use page=1 to get more topics.

Use this to:
- Find the most valuable discussions in a time range
- Research historically important threads
- Identify evergreen popular content

Returns TopicSummary objects sorted by engagement score.

Example: Use "yearly" to find the most impactful discussions,
or "daily" to see what's trending today.

Inputs: period, page. Returns: result

get_user_actionsA
Fetch a user's activity feed with optional filtering.

Args:
    username: The user's handle
    filter: Action type filter (optional). Common values:
        - 1: Likes given
        - 2: Likes received
        - 4: Topics created
        - 5: Replies posted
        - 6: Posts (all)
        - 7: Mentions
    offset: Pagination offset (0, 30, 60, ...)

Returns a list of UserAction objects showing what the user has done.

Use this for detailed activity analysis beyond just replies.
For most cases, get_user_replies or get_user_topics are simpler.

Inputs: username (required), filter, offset. Returns: result

get_user_badgesA
Fetch badges earned by a user.

Args:
    username: The user's handle
    grouped: Group badges by type (default: True)

Returns a UserBadges object with:
- badges: List of Badge objects with name, description, granted_at
- badge_types: Badge type information

Badges indicate:
- Participation milestones (first post, anniversaries)
- Community recognition (editor, leader)
- Special achievements

Use to assess user experience and trustworthiness.

Inputs: username (required), grouped. Returns: User's badges with metadata.

get_user_followersA
Fetch the list of users following a specific user.

Args:
    username: The user's handle
    page: Page number for pagination (optional)

Returns a FollowList object with:
- users: List of FollowUser objects
- total_count: Total followers

A high follower count often indicates an influential
or helpful community member.

Inputs: username (required), page. Returns: List of followed/following users.

get_user_followingA
Fetch the list of users that a user follows.

Args:
    username: The user's handle
    page: Page number for pagination (optional)

Returns a FollowList object with:
- users: List of FollowUser objects
- total_count: Total users being followed

Use to:
- Discover influential users in the community
- Find related experts
- Map social connections

Inputs: username (required), page. Returns: List of followed/following users.

get_user_reactionsB
Fetch a user's post reactions (likes, etc.).

Args:
    username: The user's handle
    offset: Pagination offset (optional)

Returns a UserReactions object with reaction data.

Use to see what content a user has reacted to,
which can indicate their interests and values.

Inputs: username (required), offset. Returns: User's post reactions.

get_user_repliesA
Fetch replies/posts made by a user in other topics.

Args:
    username: The user's handle
    offset: Pagination offset (0, 30, 60, ...)

Returns a list of UserAction objects with:
- topic_id: Which topic they replied to
- post_number: Their post number in that topic
- title: Topic title
- excerpt: Preview of their reply
- created_at: When they replied

Use this to:
- See a user's contributions across topics
- Find their data points and experiences
- Evaluate the quality of their participation

Paginate with offset in increments of 30.

Inputs: username (required), offset. Returns: result

get_user_summaryA
Fetch a comprehensive summary of a user's profile.

Args:
    username: The user's handle (case-insensitive)

Returns a UserSummary object with:
- user_id: User ID
- username: Username
- stats: UserStats with posts, topics, likes given/received, etc.
- badges: List of recent Badge objects
- top_topics: Most successful topics
- top_replies: Most successful replies

Use this to:
- Evaluate a user's credibility and experience
- Find their most valuable contributions
- Understand their participation level

The summary provides a quick overview without fetching
individual post histories.

Inputs: username (required). Returns: Comprehensive user profile summary.

get_user_topicsA
Fetch topics created by a specific user.

Args:
    username: The user's handle
    page: Page number for pagination (optional)

Returns a list of topic objects with:
- id: Topic ID
- title: Topic title
- posts_count: Number of replies
- views: View count
- created_at: When created
- category_id: Forum category

Use this to:
- See what discussions a user has initiated
- Find expert users in specific areas
- Research a user's areas of interest

Paginate by incrementing the page parameter.

Inputs: username (required), page. Returns: result

list_users_with_badgeA
List all users who have earned a specific badge.

Args:
    badge_id: The numeric badge ID
    offset: Pagination offset (optional)

Returns a dictionary with user badge information.

Use to find community members with specific achievements
or recognition levels.

Inputs: badge_id (required), offset. Returns: object

loginA
Authenticate with USCardForum credentials.

Args:
    username: Your forum username
    password: Your forum password
    second_factor_token: 2FA code if you have 2FA enabled (optional)

IMPORTANT: Only use this if you need authenticated features like:
- Reading notifications
- Bookmarking posts
- Subscribing to topics

Most read operations work without authentication.

Returns a LoginResult with:
- success: Whether login succeeded
- username: Logged-in username
- error: Error message if failed
- requires_2fa: Whether 2FA is required

The session remains authenticated for subsequent calls.

Security note: Credentials are used only for this session
and are not persisted.

Inputs: username (required), password (required), second_factor_token. Returns: Result of a login attempt.

search_forumA
Search USCardForum for topics and posts matching a query.

Args:
    query: Search query string. Supports Discourse operators:
        - Basic: "chase sapphire bonus"
        - In title only: "chase sapphire in:title"
        - By author: "@username chase"
        - In category: "category:credit-cards chase"
        - With tag: "#amex bonus"
        - Exact phrase: '"sign up bonus"'
        - Exclude: "chase -sapphire"
        - Time: "after:2024-01-01" or "before:2024-06-01"

    page: Page number for pagination (starts at 1)

    order: Sort order for results. Options:
        - "relevance": Best match (default)
        - "latest": Most recent first
        - "views": Most viewed
        - "likes": Most liked
        - "activity": Recent activity
        - "posts": Most replies

Returns a SearchResult object with:
- posts: List of matching SearchPost objects with excerpts
- topics: List of matching SearchTopic objects
- users: List of matching SearchUser objects
- grouped_search_result: Metadata about result counts

Example queries:
- "Chase Sapphire Reserve order:latest" - Recent CSR discussions
- "AMEX popup in:title" - Topics about AMEX popup in title
- "data point category:credit-cards" - Data points in CC category
- "@expert_user order:likes" - Most liked posts by a user

Pagination: If more results exist, increment page parameter.

Inputs: query (required), page, order. Returns: Complete search results.

subscribe_topicA
Set your notification level for a topic. REQUIRES AUTHENTICATION.

Args:
    topic_id: The topic ID to subscribe to
    level: Notification level:
        - 0: Muted (no notifications)
        - 1: Normal (only if mentioned)
        - 2: Tracking (notify on replies to your posts)
        - 3: Watching (notify on all new posts)

Must call login() first.

Returns a SubscriptionResult with:
- success: Whether subscription succeeded
- notification_level: The new notification level

Use to:
- Watch topics for all updates (level=3)
- Mute noisy topics (level=0)
- Track topics you've contributed to (level=2)

Inputs: topic_id (required), level. Returns: Result of subscribing to a topic.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 22 tools

    Disambiguation4/5

    Most tools have distinct purposes, but some overlap exists, such as get_user_replies and get_user_actions, which could cause confusion. However, descriptions clarify their differences, and tools like get_topic_posts and get_all_topic_posts are well-differentiated for pagination vs. bulk fetching.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern, such as get_topic_posts, bookmark_post, and search_forum. The naming is uniform and predictable, making it easy for agents to understand the action and target resource.

    Tool Count4/5

    With 22 tools, the count is slightly high but reasonable for a forum server covering categories, topics, posts, users, search, and authentication. It provides comprehensive functionality without being overwhelming, though some tools like get_user_actions and get_user_replies could potentially be consolidated.

    Completeness5/5

    The tool set offers complete coverage for a forum domain, including CRUD-like operations (e.g., login, bookmark, subscribe), extensive read capabilities (e.g., get topics, posts, users, categories), and search functionality. There are no obvious gaps, and agents can perform typical forum interactions without dead ends.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      C
      maintenance
      Enables AI agents to interact with Discourse forums through search, reading topics/posts, managing categories and users. Supports secure authentication and optional write operations with rate limiting.
      14
      21,085 npm
      80
      MIT
    • A
      license
      Not graded
      quality
      Not graded
      maintenance
      Enables interaction with USCardForum.com, a Discourse-based community for US credit cards and miles. Provides 22 tools for discovering topics, reading posts, researching user profiles, and managing authenticated actions like notifications and bookmarks.
      MIT
    • A
      license
      A
      quality
      Not graded
      maintenance
      Enables interaction with USCardForum, a Discourse-based community for US credit cards and points. Supports topic discovery, content reading, user research, forum search, and authenticated actions like notifications and bookmarks.
      22
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables interaction with USCardForum, a Discourse community focused on US credit cards and points, providing 22 tools for discovering topics, reading content, researching user profiles, and managing authenticated actions like notifications and bookmarks.
      22
      MIT