trends-mcp

Trends MCP Server

A FastMCP-based server for free entity normalization and attention context.

This project is intentionally opinionated:

• it exposes semantic tools, not raw provider dumps
• it treats Google Knowledge Graph MIDs as canonical entity hints
• it is meant to pair with news and crypto MCPs
• it should remain useful even when historical trend requests are flaky

What it does

Current tools:

• resolve_entity — return candidate entity matches and the best Knowledge Graph MID
• get_related_queries — show the search terms surrounding an entity
• get_related_topics — show the topic neighborhood around an entity
• get_ledger_recent — inspect the newest history entries
• get_ledger_summary — summarize what the ledger is saying
• get_entity_history — inspect history for one entity or MID
• prune_history — delete stored snapshots older than the retention window
• get_interest_over_time — show attention over time for a keyword or entity
• compare_interest — compare attention between multiple keywords or entities
• get_attention_score — compact attention score for a known entity

Run

With uv

uv sync
./run.sh

With pip

pip install -r requirements.txt
./run.sh

mcporter

If you use mcporter, point it at:

--conf ~/.openclaw/workspace/conf/mcporter.json

Example smoke test:

$ mcporter --config ~/.openclaw/workspace/config/mcporter.json call trends.get_interest_over_time keyword=bitcoin timeframe=7d

Entity resolution example:

$ mcporter --config ~/.openclaw/workspace/config/mcporter.json call trends.resolve_entity keyword=bitcoin

Related queries example:

mcporter --config ~/.openclaw/workspace/config/mcporter.json call trends.get_related_queries keyword=bitcoin

Related topics example:

mcporter --config ~/.openclaw/workspace/config/mcporter.json call trends.get_related_topics keyword=bitcoin

History example:

mcporter --config ~/.openclaw/workspace/config/mcporter.json call trends.get_entity_history entity=BTC

Suggested smoke tests:

python -m pytest
mcporter --config ~/.openclaw/workspace/config/mcporter.json call trends.resolve_entity keyword=bitcoin
mcporter --config ~/.openclaw/workspace/config/mcporter.json call trends.get_related_queries keyword=bitcoin
mcporter --config ~/.openclaw/workspace/config/mcporter.json call trends.get_related_topics keyword=bitcoin

Ledger note:

sqlite3 data/trends_history.db 'select id, ts, tool, keyword, normalized_keyword, mid from snapshots order by id desc limit 20;'

Prune history example:

mcporter --config ~/.openclaw/workspace/config/mcporter.json call trends.prune_history retention_days=30

History pruning runs automatically once per day when snapshots are being written.

The server listens on:

• http://0.0.0.0:8507
• health: http://127.0.0.1:8507/health
• MCP SSE mount: http://127.0.0.1:8507/mcp

Scripts

• run.sh — start the server in the background
• killserver.sh — stop a PID recorded in logs/server.pid
• restart.sh — kill, then run again

Logs are written to logs/server.log.

Design notes

The long-term shape of this MCP should be:

1. provider adapters in providers/
2. entity normalization and aliasing
3. cache / TTL for recent trend series
4. simple signal heuristics
5. MCP tools that return compact, interpretable outputs

Next obvious work

• replace the fake series generator with a real Google Trends adapter
• add cache storage
• load aliases from JSON
• add detect_trending_entities
• add get_related_queries