USCardForum MCP Server
Provides comprehensive access to USCardForum, a Discourse-based community focused on US credit cards, points, and miles. Enables browsing hot/new/top topics, full-text search, reading topic posts with pagination, researching user profiles and activity, managing bookmarks and subscriptions, and accessing notifications for authenticated users.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@USCardForum MCP Server show me the latest hot topics about Chase Sapphire cards"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 configInstallation
Using UV (Recommended)
# Clone the repository
git clone https://github.com/uscardforum/mcp-server.git
cd uscardforum
# Install with UV
uv sync
# Run the server
uv run uscardforumUsing 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
uscardforumConfiguration
Environment Variables
Variable | Default | Description |
|
| Transport mode: |
|
| HTTP server host (for |
|
| HTTP server port (for |
| (none) | Bearer token for MCP auth ( |
|
| Forum base URL |
|
| Request timeout in seconds |
| (none) | Auto-login username (optional) |
| (none) | Auto-login password (optional) |
Transport Modes
The server supports three transport modes:
stdio(default): Standard input/output, used by Cursor and Claude Desktopsse: Server-Sent Events over HTTPstreamable-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/mcpStreamable 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-tokenThis 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
# 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=1Railway
# 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 openRender
Connect your GitHub repository to Render
Create a new Web Service
Select Docker as the runtime
Set environment variables in the dashboard:
MCP_TRANSPORT=streamable-httpNITAN_TOKEN=your-secret-tokenNITAN_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 itFly.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 logsGoogle Cloud Run
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.yamlDigitalOcean 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 variablesKoyeb
# 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-tokenCloudflare Containers
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 -fDocker Hub: uscarddev/uscardforum-mcp
Available tags:
latest- Latest stable releasetagname- 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 |
|
| ā | Set to |
|
| HTTP server bind address | |
|
| HTTP server port (some platforms override this) | |
| Bearer token for MCP authentication | ||
|
| Forum base URL | |
|
| Request timeout in seconds | |
| Forum auto-login username | ||
| 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/mcpRailway:
https://your-app.up.railway.app/mcpRender:
https://your-app.onrender.com/mcpFly.io:
https://your-app.fly.dev/mcpCloud Run:
https://your-app-xxxxx-uc.a.run.app/mcpDigitalOcean:
https://your-app.ondigitalocean.app/mcpKoyeb:
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-missingDomain 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: LikesUser 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 previewSearch 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 usersAuth 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 infoAPI Modules
The backend is split into focused API modules:
Module | Purpose |
| Topic lists, posts, pagination |
| Profiles, activity, badges, social |
| Full-text search |
| Category mappings |
| 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 |
|
| Currently trending topics by engagement |
|
| Latest topics by creation time |
|
| Top topics by period (daily/weekly/monthly/yearly) |
|
| Full-text search with operators |
|
| Category ID to name mapping |
š Reading ā Access Topic Content
Tool | Return Type | Description |
|
| Topic metadata (check post count first!) |
|
| Fetch ~20 posts starting at position |
|
| Fetch all posts with auto-pagination |
š¤ Users ā Profile & Activity Research
Tool | Return Type | Description |
|
| Profile overview and stats |
|
| Topics created by user |
|
| User's reply history |
|
| Full activity feed |
|
| Badges earned by user |
|
| Who the user follows |
|
| Who follows the user |
|
| Reactions given/received |
|
| Find users with specific badge |
š Auth ā Authenticated Actions (requires login)
Tool | Return Type | Description |
|
| Authenticate with forum credentials |
|
| Check authentication status |
|
| Fetch user notifications |
|
| Bookmark a post for later |
|
| Set topic notification level |
Available Prompts (4 Prompts, äøę)
Guided workflows for common research tasks:
Prompt | Args | Purpose |
|
| ē 究论åē¹å®äø»é¢ļ¼ę»ē»ē¤¾åŗå ±čÆ |
|
| åęēØę·čµęćč“”ē®ååÆäæ”åŗ¦ |
|
| ę„ę¾ēØę·ę„åēēå®ę°ę®ē¹ |
|
| ęÆč¾äø¤å¼ äæ”ēØå”ē社åŗč®Øč®ŗ |
Available Resources (3 Resources)
Quick-access static data:
URI | Description |
| Category ID ā name mapping (JSON) |
| Top 20 trending topics (JSON) |
| 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
Domain Models (
models/)Pydantic models for all return types
Strong typing and validation
Clear documentation
API Modules (
api/)Focused functionality per domain
Inherits from BaseAPI for HTTP
Returns domain models
Client (
client.py)Composes all API modules
Unified interface
Session management
MCP Server (
server.py)FastMCP tool definitions
Bearer token authentication
Extensive docstrings (Chinese)
Prompts and resources
Security
MCP Authentication: Bearer token via HTTP
Authorizationheader (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:
Fork the repository
Create a feature branch
Submit a pull request
Acknowledgments
Built with FastMCP
Domain models with Pydantic
Cloudflare bypass via cloudscraper
Discourse API documentation at docs.discourse.org
Available Tools
22 toolsbookmark_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
Scored across 22 tools
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.
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.
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.
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
Search or monitor any Flarum-powered forum for discussions, replies, participants, dates, andā¦
Browse and manage Reddit posts, comments, and threads. Fetch user activity, explore hot/new/risingā¦
Reddit analytics and audience research for AI assistants: find subreddits for a topic, see who is in them, the best time to post, posting rules and Reddit brand mentions. KissMyPost works as a subreddit finder and Reddit marketing tool: subreddit growth and audience stats, similar subreddits, trending topics, Reddit post and mention search, and threads worth a reply. 17 read-only tools. Free API key at kissmypost.com/mcp. Not affiliated with Reddit, Inc.
Related MCP Servers
AlicenseAqualityCmaintenanceEnables 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.1421,085 npm80MIT- AlicenseNot gradedqualityNot gradedmaintenanceEnables 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
- AlicenseAqualityNot gradedmaintenanceEnables 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.22MIT
- AlicenseAqualityCmaintenanceEnables 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.22MIT