Bera MCP Server 🐻

Your friendly bear companion for Berachain development!

Bera MCP is a powerful Model Context Protocol (MCP) server that gives AI agents instant access to the entire Berachain ecosystem. Built with RAG (Retrieval Augmented Generation), it's like having a knowledgeable bear by your side that never forgets where the honey is—or in this case, where all the documentation lives!

Whether you're building DeFi protocols, integrating oracles, or deploying smart contracts, Bera MCP helps you find answers faster than you can say "Honey!" 🍯

What is Bera MCP?

Bera MCP is your go-to companion for all things Berachain. It's a smart documentation assistant that:

🐻 Roams the Berachain ecosystem: Automatically indexes and keeps up-to-date with official Berachain docs and guides
🍯 Finds the sweetest answers: Uses AI-powered semantic search to understand your questions and find the most relevant documentation
📚 Never forgets: Stores everything in a vector database so it can recall information instantly
🔄 Stays fresh: Automatically updates when new documentation is released

What Can Bera Help You With?

Bera MCP has your back (and your front) when building on Berachain:

🏗️ Smart Contract Development: Get instant answers about contract patterns, best practices, and Berachain-specific features
💎 DeFi Integrations: Understand how to integrate with Berachain's DeFi protocols and token standards
🔮 Oracle Integrations: Learn how to use Pyth, Chainlink, and other oracles on Berachain
🚀 Deployment Guides: Step-by-step instructions for deploying and managing your contracts
🧪 Testing & Debugging: Best practices for testing your Berachain applications
📖 API References: Quick access to function signatures, parameters, and return values
🎯 And everything else Berachain-related!

Just ask Bera anything, and it'll dig through the documentation to find you the perfect answer!

Features 🐻

Bera comes packed with powerful features to make your Berachain development journey smoother:

🐻 Wizard Tool (ask_berachain): Bera's superpower! Ask any question in plain English and get comprehensive, AI-powered answers with full code examples. It's like having a Berachain expert on speed dial!
🔍 Semantic Search (search_docs): Search across all documentation using natural language. No need to know exact keywords—just ask naturally!
📄 Document Retrieval (get_doc_section): Need a specific section? Bera knows exactly where everything is stored and can fetch it instantly.
🔄 Auto-Updates: Bera stays up-to-date automatically! It watches the Berachain repos and indexes new documentation as it's released.
📚 Custom Docs: Add your own markdown files to the docs/ directory, and Bera will index them too. Perfect for team-specific guides or custom integrations!

Prerequisites

Node.js 18+ and npm
OpenRouter API key (for embeddings and LLM)
Upstash Vector account (for vector storage)

Installation

1. Clone the Repository

git clone <your-repo-url>
cd bera-mcp

2. Install Dependencies

npm install

3. Set Up Environment Variables

Create a .env file in the root directory:

OPENROUTER_API_KEY=your_openrouter_api_key_here
UPSTASH_VECTOR_REST_URL=your_upstash_vector_url_here
UPSTASH_VECTOR_REST_TOKEN=your_upstash_vector_token_here

LLM_MODEL=google/gemini-2.5-flash-preview-09-2025

Required Environment Variables:

OPENROUTER_API_KEY: Your OpenRouter API key for embeddings and LLM generation
UPSTASH_VECTOR_REST_URL: Your Upstash Vector REST API URL
UPSTASH_VECTOR_REST_TOKEN: Your Upstash Vector REST API token

Optional Environment Variables:

LLM_MODEL: LLM model for generating answers (default: google/gemini-2.5-flash-preview-09-2025)
CHUNK_SIZE: Document chunk size for indexing (default: 1000)
CHUNK_OVERLAP: Overlap between chunks (default: 200)
TOP_K: Number of results for search (default: 5)

4. Set Up Upstash Vector

Create an account at Upstash
Create a new Vector database
Configure with these settings:
- Type: Dense
- Embedding Model: Custom
- Dimensions: 3072
- Metric: COSINE
Copy the REST URL and Token to your .env file

5. Build and Index

npm run build
npm run index

The indexer will:

Download Berachain docs and guides repositories
Process all markdown files
Generate embeddings
Store everything in your Upstash Vector database

Note: First-time indexing may take 10-20 minutes depending on documentation size.

6. Start the Server

npm start

The server runs on stdio and is ready to accept MCP client connections.

Installing in Cursor

Since Bera MCP uses your own API keys (OpenRouter and Upstash), you need to host it yourself. Here's how to set it up in Cursor:

Option 1: Local Installation (Recommended)

Clone and set up the server (follow installation steps above)
Add to Cursor's MCP settings (~/.cursor/mcp.json or Cursor Settings → Features → Model Context Protocol):

{
  "mcpServers": {
    "bera-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/bera-mcp/dist/cli.js"],
      "env": {
        "OPENROUTER_API_KEY": "your_key_here",
        "UPSTASH_VECTOR_REST_URL": "your_url_here",
        "UPSTASH_VECTOR_REST_TOKEN": "your_token_here"
      }
    }
  }
}

Restart Cursor to load the MCP server

Option 2: Deploy to Smithery (Recommended for Production)

Bera MCP is configured for Smithery deployment using TypeScript runtime. The smithery.yaml file is already set up.

Push your repository to GitHub (make sure .env is in .gitignore!)
Deploy to Smithery:
- Go to Smithery
- Sign in and connect your GitHub account
- Click "Create Server" or "New Deployment"
- Select your bera-mcp repository
- Smithery will automatically detect the smithery.yaml configuration
Configure Server Settings:
- In the Smithery dashboard, go to your server's settings
- Add the following configuration values:
  - openrouterApiKey: Your OpenRouter API key
  - upstashUrl: Your Upstash Vector REST URL
  - upstashToken: Your Upstash Vector REST token
  - llmModel: Optional - LLM model name (default: google/gemini-2.5-flash-preview-09-2025)
- These will be securely stored and passed to your server
Deploy:
- Click "Deploy" in the Smithery dashboard
- Smithery will build and deploy your server automatically
- Wait for the deployment to complete (usually 2-5 minutes)
Index Documentation (First Time Only):
- After deployment, you'll need to run the indexer once to populate the vector database
- You can do this locally or set up a one-time indexing job
- Run: npm run index (this requires your .env file with API keys)
Connect from Cursor:
- In Cursor, go to Settings → Features → Model Context Protocol
- Add a new MCP server using the Smithery connection URL
- The URL format will be: https://server.smithery.ai/your-server/mcp
- Configure with your API keys in the connection settings

Note: The server configuration schema is automatically generated from configSchema in src/index.ts, so Smithery will show a form for entering your API keys when connecting.

MCP Tools

`ask_berachain` 🐻

The main wizard tool for asking questions about Berachain development.

Parameters:

question (required): Your question about Berachain
maxContextChunks (optional): Number of document chunks to use (default: 5)

Example:

{
  "question": "How do I integrate Pyth oracles on Berachain?",
  "maxContextChunks": 5
}

Returns: Comprehensive answer with code examples, sources, and citations.

`search_docs` 🔍

Semantic search across all Berachain documentation.

Parameters:

query (required): Search query
topK (optional): Number of results (default: 5)

Example:

{
  "query": "HONEY token oracle price",
  "topK": 3
}

Returns: Array of relevant document chunks with scores and metadata.

`get_doc_section` 📄

Retrieve a specific documentation section by file path.

Parameters:

filePath (required): Relative file path (e.g., "PYTH_ORACLES_BERACHAIN.md")
repo (required): Repository name ("docs", "guides", or "local")

Example:

{
  "filePath": "PYTH_ORACLES_BERACHAIN.md",
  "repo": "local"
}

Returns: All chunks from the specified file, sorted by order.

Adding Custom Documentation

Place markdown files in the docs/ directory. They will be automatically indexed on the next npm run index run.

Example:

mkdir -p docs
cp your-guide.md docs/
npm run index

Updating Documentation

To update the indexed documentation:

npm run index

This will:

Pull the latest changes from berachain/docs and berachain/guides
Re-index all documentation
Update your vector database

Project Structure

bera-mcp/
├── src/
│   ├── cli.ts              # MCP server entry point
│   ├── server.ts           # MCP server setup
│   ├── config.ts           # Configuration management
│   ├── indexer.ts          # Indexing pipeline
│   ├── indexer-cli.ts      # CLI for indexing
│   ├── downloader.ts      # Git repository downloader
│   ├── processor.ts        # Markdown processing and chunking
│   ├── embeddings.ts       # Embedding generation
│   ├── vectorStore.ts      # Upstash Vector integration
│   └── tools/
│       ├── query.ts         # ask_berachain wizard tool
│       └── search.ts        # search_docs and get_doc_section tools
├── docs/                    # Custom documentation (auto-indexed)
├── data/                    # Downloaded repositories (gitignored)
├── dist/                    # Compiled output (gitignored)
└── .env                     # Environment variables (gitignored)

Security Notes

⚠️ Important: Never commit your .env file or API keys to version control!

The .gitignore file is configured to exclude:

.env and all environment files
data/ directory (downloaded repos)
node_modules/
dist/ (compiled code)

Always use environment variables or secure secret management when deploying.

Troubleshooting

"OPENROUTER_API_KEY environment variable is required"

Make sure your .env file exists and contains OPENROUTER_API_KEY.

"UPSTASH_VECTOR_REST_URL and UPSTASH_VECTOR_REST_TOKEN environment variables are required"

Set up your Upstash Vector database and add the credentials to .env.

Indexing fails or takes too long

Check your OpenRouter API key has sufficient credits
Verify your Upstash Vector database is accessible
Check network connectivity for downloading repositories

MCP server not connecting in Cursor

Verify the path in mcp.json is absolute and correct
Check that npm run build completed successfully
Ensure environment variables are set in Cursor's MCP configuration
Restart Cursor after configuration changes

License

MIT

Contributing

Contributions welcome! Please ensure:

All code is properly typed (TypeScript)
Environment variables are documented
Security best practices are followed
Tests are added for new features

Support

Got questions? Stuck on something? Bera's here to help!

🐛 Found a bug? Open an issue on GitHub
💡 Have an idea? We'd love to hear it!
🤝 Want to contribute? Pull requests are always welcome!

Built with 🍯 for the Berachain developer community 🐻

May your contracts deploy smoothly and your honey flow freely!

Name		Name	Last commit message	Last commit date
Latest commit History 12 Commits
.smithery		.smithery
docs		docs
src		src
.env.example		.env.example
.gitignore		.gitignore
README.md		README.md
askbera.png		askbera.png
package-lock.json		package-lock.json
package.json		package.json
save-remaining-kodiak-docs.js		save-remaining-kodiak-docs.js
smithery.yaml		smithery.yaml
tsconfig.json		tsconfig.json

SerPepe/bera-mcp

Folders and files

Latest commit

History

Repository files navigation

Bera MCP Server 🐻

What is Bera MCP?

What Can Bera Help You With?

Features 🐻

Prerequisites

Installation

1. Clone the Repository

2. Install Dependencies

3. Set Up Environment Variables

4. Set Up Upstash Vector

5. Build and Index

6. Start the Server

Installing in Cursor

Option 1: Local Installation (Recommended)

Option 2: Deploy to Smithery (Recommended for Production)

MCP Tools

ask_berachain 🐻

search_docs 🔍

get_doc_section 📄

Adding Custom Documentation

Updating Documentation

Project Structure

Security Notes

Troubleshooting

"OPENROUTER_API_KEY environment variable is required"

"UPSTASH_VECTOR_REST_URL and UPSTASH_VECTOR_REST_TOKEN environment variables are required"

Indexing fails or takes too long

MCP server not connecting in Cursor

License

Contributing

Support

About

Topics

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

`ask_berachain` 🐻

`search_docs` 🔍

`get_doc_section` 📄

Packages