Describe your research topic → receive a submission-ready LaTeX draft.

An AI-assisted research workflow for economic and financial research — from idea to LaTeX manuscript draft. Integrates 43 MCP server directories (41 real implementations + 2 mock-only for institutional data + 3 opt-in legal-risk), modern causal inference (DID/IV/RDD/PSM/GMM, see dependency notes), LaTeX formatting for 30 journal templates (English/Chinese/Japanese/German), and AI-assisted review loops.

⚠️ Important: This tool generates manuscript drafts that require human review before submission. All causal identification strategies, statistical results, and citations must be verified by a researcher.

⚠️ Legal Risk Servers (CNKI / Wanfang / Chinese Literature): These 3 MCP servers scrape websites that prohibit automated access. They are disabled by default for ALL users — including the full profile. To use them, you must: (1) read LEGAL_CONSENT.md carefully, (2) set CLI_ACCEPT_RISK=cnki,wanfang,chinese-literature in your environment. Without this variable, these servers are never loaded. Users take full legal responsibility.

🔴 科研诚信 — Mock 数据默认关闭 (2026-06-28): 以下 5 个 MCP 服务器返回模拟/硬编码/公开数据快照，默认禁用，防止用户基于伪造数据发表错误结论：

• user_nber_wp — 返回 3 个编造的 paper_id（w32456/w32098/w31567）+ 硬编码引用计数
• user_bea_data — 无论 year 参数如何，都返回硬编码 GDP（$27.36T）
• user_csmar — 文件头自承认"提供模拟数据用于演示"
• user_wuhan_stats / user_macro_datas — 公开数据快照（统计局发布，非实时 API）

临时启用（如演示场景）：export MCP_MOCK_MODE=allow。禁止用于任何拟发表的研究输出。详见 docs/MOCK_DATA_POLICY.md。

Languages: 🇨🇳 简体中文 (默认) · 🇬🇧 English

$ python scripts/agent_pipeline.py --topic "Carbon trading and green innovation"

From a one-line research question to a structured research plan — time and API costs vary by topic complexity, data availability, and LLM model used. All eight stages (idea generation → literature review → novelty check → empirical design → data acquisition → analysis → writing → adversarial review) include human-in-the-loop checkpoints.

• Built for economists, not generic AI demos — every default is calibrated for the Journal of Finance / 经济研究 standard (DID with heterogeneous treatment effects, cluster-robust SEs at the firm level, 19 robustness checks, parallel-trend plots).
• 43 MCP server directories — covers A-share financials, US equities, global macro (FRED/World Bank/IMF/OECD/BEA), and 200M+ academic papers. 41 directories have full Python implementations; 2 are mock-only (user-csmar, user-wind require institutional accounts); 3 are opt-in legal-risk (CNKI, Wanfang, Chinese Literature). Free alternatives exist via user-financial (akshare) and user-yfinance.
• ~20 econometric method implementations, not just OLS — standard DID, event study, Bacon decomposition, staggered DID (Callaway-Sant'Anna/Sun-Abraham/Borusyak/Goodman-Bacon, requires pip install diff-in-diff2), synthetic control, instrumental variables (requires linearmodels), panel GMM, RDD, event studies, mediation, and more. See CLAUDE.md for the full list with dependency notes.
• 30 journal templates, English/Chinese/Japanese/German — JF, JFE, RFS, JAE, Econometrica, 经济研究, 金融研究, 管理世界, 会计研究, 中国工业经济.
• 18 specialised AI skills (Claude Code / Cursor / GitHub Copilot) — idea discovery, literature review, novelty check, experiment design, data acquisition, paper drafting, figure generation, LaTeX compilation, review loops.
• Human-in-the-loop, never autonomous fabrication — every stage requires explicit checkpoint approval; data sources are verified before use; no synthetic data without user consent.

For Chinese users: The most comprehensive guide is 使用指南.md — a complete 13-chapter manual covering installation, workflows, data sources, econometric methods, paper writing, and FAQ.

Not sure? If you've ever spent days downloading data, running regressions, formatting LaTeX tables, or searching for related work — this tool is for you.

register_mcp_servers.py supports 4 user-type profiles — pick the one matching your hardware and use case:

# 1) Dry-run first (推荐先看)
python scripts/register_mcp_servers.py --profile academic --prune --dry-run

# 2) Actually apply
python scripts/register_mcp_servers.py --profile academic --prune

# 3) List current registration
python scripts/register_mcp_servers.py --list

See config/mcp_profiles.json for full server lists and the 使用指南.md chapter on installation for step-by-step.

Default behavior: without --profile, all 43 MCP servers are registered (matches full profile). Use --prune to remove out-of-profile servers.

The project supports macOS, Linux, and Windows with platform-specific entry points:

This project supports two entry points — pick the one that matches your workflow:

The AI agent handles the full pipeline end-to-end. No need to remember commands.

# 1) Install once
./run.sh                    # macOS / Linux
run.bat                     # Windows

# 2) Health check
python scripts/health_check.py

# 3) Start an AI Agent (Claude Code / Cursor / Codex) and describe your research:
# "帮我研究关税政策对A股出口型企业创新的影响，设计一篇发表在经济研究的实证论文"

The AI agent automatically calls all 8 pipeline stages, MCP data sources, and LaTeX generators. Each stage requires your checkpoint approval before proceeding.

Run individual scripts directly for fine-grained control:

# Full research pipeline
python scripts/agent_pipeline.py --topic "Carbon trading and green innovation"

# Research execution layer (DID/IV/RDD + writing)
python scripts/research_framework/pipeline.py --topic "Carbon trading and green innovation"

# Demo: institutional-grade financial report
python scripts/demo_research_report.py --stock 000001.SZ

# MCP tool discovery
python scripts/core/mcp_tool_market.py --search "gdp" --report

# Journal template generation
python scripts/journal_template.py --list
python scripts/journal_template.py --generate JFE output/paper.tex

• macOS: Keychain is native; keyring uses KeychainBackend automatically
• Linux: Keyring uses SecretService (gnome-keyring). For Chinese fonts, install fonts-noto-cjk:

  sudo apt install fonts-noto-cjk fonts-wqy-zenhei

• Windows: Keyring uses Credential Manager. Chinese fonts (SimHei, Microsoft YaHei) come pre-installed

• ✅ All scripts/*.py entry points
• ✅ 43 MCP servers (pure Python stdlib)
• ✅ Checkpoint (fcntl.flock falls back to no-op on Windows)
• ✅ 2,234 unit tests (pytest --collect-only; CI matrix: Ubuntu + macOS; no Windows)

• ⚠️ event_monitor.py uses signal.pause() which is Unix-only; on Windows it falls back to a polling loop
• ⚠️ keychain_setup.py is macOS-specific; for Windows/Linux, use the cross-platform keyring via scripts/keychain_manager.py
• ⚠️ core/sandbox.py uses os.fork (Unix-only); falls back to subprocess on Windows

Describe your research in plain Chinese — the agent handles the rest:

帮我研究关税政策对A股出口型企业创新的影响，设计一篇发表在经济研究的实证论文

What the agent produces automatically:

Footnote on numbers: The table above describes the core pipeline output stages. Idea generation, novelty verification, and literature review are separate stages that run before or in parallel. MCP server counts include 43 registered servers; some require institutional/paid accounts (Tushare Pro, Wind, CSMAR, CEIC) while others work without API keys (yfinance, akshare, World Bank, IMF, OECD, FRED, ArXiv, NBER, OpenAlex). See dependency notes in CLAUDE.md.

Architecture overview:

Multi-agent pipeline: User Input → AI Agent → 5-Stage Research Pipeline (outline → literature → plotting → writing → refinement, with optional HITL gates at each stage) → 43 MCP Servers → ~30 Econometric Methods → 20 Chart Types → LaTeX Paper

Note: Demo assets are in .github/demo/ and docs/assets/. The project is actively maintained.

# 1. Clone the repository
git clone https://github.com/csmar432/finai-research-workflow.git
cd finai-research-workflow

# 2. Install dependencies
python3 -m venv .venv && source .venv/bin/activate
pip install -e .

# Optional: install econometrics extras (includes diff-in-diff2 for CS/BJS/Gardner DiD)
pip install -e ".[econometrics]"

# 3. Configure API key (at least one required)
cp .env.example .env
# Edit .env and add: DEEPSEEK_API_KEY=sk-your-key
# Other supported: ANTHROPIC_API_KEY, OPENAI_API_KEY

# 4. Run your first research pipeline
python scripts/research_framework/pipeline.py --topic "碳排放权交易对企业绿色创新的影响"

# Or use an AI Agent (recommended) for the full interactive workflow

Simply describe your research goal in natural language:

帮我分析碳排放权交易对企业绿色创新的影响，设计一篇实证论文，发表在经济研究

AI Agent will automatically call all necessary modules.

The system uses a layered agent architecture with an AI Agent (Claude Code / Cursor / Codex) as the orchestrator:

Key numbers (auto-generated by scripts/count_assets.py):

Run python scripts/count_assets.py to regenerate these numbers. They are checked into README as a snapshot of the latest count; CI is the source of truth.

43 servers total: 28 work without API keys, 12 require API keys, 3 are opt-in legal-risk. See MCP Tool Marketplace for the complete catalog.

Badge	Meaning
💰 Paid	Requires institutional/paid account (Tushare Pro / Wind / CSMAR / CEIC)
⚠️ Limited	Free tier available but rate-limited or requires registration
✅ Free	No account required — works out of the box

A-share users without institutional accounts: user-yfinance (US/ADR) and user-financial (akshare free tier) cover basic equity/macro needs. Paid A-share data (CSMAR/Wind/Tushare Pro) requires institutional accounts.

See MCP Tool Marketplace Tutorial for the complete catalog.

Each skill is documented in .claude/skills/ (Claude Code) and .github/skills/ (GitHub Copilot). In Cursor, use the Skill: command directly.

# Paper pipeline
python scripts/research_framework/pipeline.py --topic "碳排放权交易对企业绿色创新的影响"

# Financial report
python scripts/demo_research_report.py --stock 000001.SZ

# MCP tool marketplace
python scripts/core/mcp_tool_market.py --search "gdp" --report

# Event monitor
python scripts/event_monitor.py --interval 300 --test

# Literature review
python scripts/research_framework/pipeline.py --mode lit-review --topic "carbon trading innovation"

# Or use an AI Agent directly
# "帮我做碳交易创新领域的文献综述"

# Journal template
python scripts/journal_template.py --list
python scripts/journal_template.py --generate JFE output/paper.tex

# Dashboard
streamlit run scripts/dashboard.py --server.port 8050

1. Create directory: mcp_servers/user_your_server/
2. Add SERVER_METADATA.json
3. Add tool definitions in tools/*.json
4. Register in Cursor MCP settings
5. Rebuild registry: python scripts/core/mcp_tool_market.py --dir mcp_servers

See MCP Marketplace Tutorial for full guide.

1. Create file: scripts/research_directions/carbon_economics.py (copy from an existing direction like green_finance.py as template)
2. Define ResearchDirection class with:
   • Research questions
   • Data requirements
   • Hypothesis derivation
   • Empirical strategy
3. Add to scripts/research_directions/__init__.py

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit changes (git commit -m 'Add amazing feature')
4. Push to branch (git push origin feature/amazing-feature)
5. Open a Pull Request

See CONTRIBUTING.md for full guidelines.

This project is licensed under the MIT License. See LICENSE for details.

• 5 轮交互式澄清模式参考 Night Owl Research Agent 设计（2026-06-27 命名已重命名）
• Inspired by PaperOrchestra multi-agent architecture
• Data powered by akshare, yfinance, World Bank API, and Tushare Pro

flowchart TD
    Start([User inputs research topic]) --> P1[1. Outline<br/>Research framework + venue template]
    P1 -->|HITL gate| P2[2. Literature Review<br/>OpenAlex + ArXiv + Context7 + NBER]
    P2 -->|HITL gate| P3[3. Plotting<br/>Parallel chart generation]
    P3 --> P4[4. Paper Writing<br/>Full manuscript draft]
    P4 -->|HITL gate| P5[5. Refinement<br/>Multi-round adversarial review]
    P5 --> Done([LaTeX manuscript draft])

    IdeaStage[Idea Generation<br/>Stage 1 of 3] -.->|optional| P1
    DataStage[Data Acquisition<br/>Stage 2 of 3] -.->|feeds into| P3
    NoveltyStage[Novelty Check<br/>Stage 3 of 3] -.->|feeds into| P1

    style P1 fill:#e94560,color:#fff
    style P2 fill:#0f3460,color:#fff
    style P3 fill:#533483,color:#fff
    style P4 fill:#16213e,color:#fff
    style P5 fill:#0f3460,color:#fff
    style IdeaStage fill:#444,color:#fff,stroke-dasharray:3
    style DataStage fill:#444,color:#fff,stroke-dasharray:3
    style NoveltyStage fill:#444,color:#fff,stroke-dasharray:3

    classDef hitl_gate stroke:#f0ad4e,stroke-width:3px
    class P1,P2,P4,P5 hitl_gate

Pipeline stages note: The core pipeline has 5 stages (outline → literature → plotting → writing → refinement) with optional HITL gates. Idea generation, novelty verification, and data acquisition run as parallel/prior stages. The research framework CLI (scripts/research_framework/pipeline.py) provides a focused DID/IV/RDD analysis mode.

flowchart LR
    Req[Data Request<br/>e.g. A-share ROA] --> Router{Smart Router}
    Router --> Tier1[Tier 1<br/>CSMAR/Wind<br/>Highest quality]
    Router -->|unavailable| Tier2[Tier 2<br/>Tushare<br/>+ patent data]
    Router -->|no key| Tier3[Tier 3<br/>akshare<br/>Free, slower]
    Router -->|no data| Tier4[Tier 4<br/>yfinance/synthetic<br/>Last resort]
    Tier1 --> Cache[(Local Cache<br/>SQLite)]
    Tier2 --> Cache
    Tier3 --> Cache
    Tier4 --> Cache
    Cache --> Result[Validated Data +<br/>Provenance Hash]

    style Tier1 fill:#28c840,color:#fff
    style Tier2 fill:#febc2e,color:#000
    style Tier3 fill:#0f3460,color:#fff
    style Tier4 fill:#e94560,color:#fff
    style Cache fill:#1a1a2e,color:#fff

flowchart TD
    DID[DID with Staggered Treatment] --> Check{Never-treated<br/>available?}
    Check -->|Yes| Q1{Heterogeneous<br/>effects suspected?}
    Check -->|No| Q2{Continuous<br/>treatment?}
    Q1 -->|Yes| CS[Callaway-Sant'Anna<br/>2021 - default]
    Q1 -->|No| SA[Sun-Abraham<br/>2021]
    Q1 -->|Wants imputation| BJJ[Borusyak-Jaravel-Spiess<br/>2024]
    Q2 -->|Yes| ContDID[Continuous DID<br/>Callaway-DiTraglia 2024]
    Q2 -->|No| Decompose[Bacon Decomposition<br/>diagnose TWFE bias]
    CS --> Synth[Synthetic DiD<br/>Arkhangelsky 2021]
    SA --> Synth
    BJJ --> Synth

    style CS fill:#e94560,color:#fff
    style SA fill:#0f3460,color:#fff
    style BJJ fill:#533483,color:#fff
    style Synth fill:#16213e,color:#fff
    style Decompose fill:#16213e,color:#fff
    style ContDID fill:#0f3460,color:#fff

This project is maintained by @csmar432.

• 🐛 Bug reports & feature requests: GitHub Issues
• 💬 Questions & ideas: GitHub Discussions
• 🔒 Security disclosures: GitHub Security Advisories
• 💖 Sponsor / support: GitHub Sponsors · 爱发电

Contributions of all sizes are welcome — see CONTRIBUTING.md for the workflow.

If this project helps your research, give it a ⭐ — it tells other economists the project is worth their time.

If you use FinAI Research Workflow in published research, please cite it as:

@software{finai2026,
  title  = {FinAI Research Workflow: An End-to-End AI Agent Pipeline for Economic and Financial Research},
  author = {csmar432},
  year   = {2026},
  month  = jun,
  url    = {https://github.com/csmar432/finai-research-workflow},
  note   = {GitHub repository. For a permanent DOI, publish on Zenodo and update this field.}
}

• dowhy — causal inference library (8.1K ⭐)
• StatsPAI — agent-native causal inference toolkit (50 ⭐)
• moderndid — GPU-accelerated modern DiD
• diff-diff — sklearn-like DiD in Python
• PaperOrchestra — Google's multi-agent paper writing (58 ⭐)
• E2ER-project — end-to-end empirical research pipeline
• econ-paper-studio — agent-native CLI for empirical economics

MIT License — see LICENSE for the full text.